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.
When these models are used for scoring, users must retrieve the model by passing relevant license information. See the license argument for details.
- 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.
- 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 retrieve_byom() take precedence and is used for function execution.
- 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 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 retrieve_byom() take precedence and is used for function execution.
- If you specify schema_name, table_name has to be specified, else exception is raised.
See table in save_byom() that shows different system behaviors based on different input combinations.
- 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.
- If the license key is stored in a variable, users can pass it as string.
- 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.
- require_license specifies whether the model to be retrieved is associated with a license.
The default value is False. If set to True, license information set by set_license() is retrieved.
If license parameters are passed, then this argument is ignored.
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.
>>> 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.
- Save a model in the same database without license.
- Store a license in a variable "lic_key", for "model5" in example 3.
>>> lic_key = "eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI"
- Store a license in a table "license" in the column "license_key", for example 5.
>>> # 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 database ""mldb", for example 6.
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
Example 7: Retrieve a model with license key set at session level by set_license(), license is passed as a variable
In this example, retrieve a model with id 'model5' from the table 'byom_models', with license key stored by set_license() in a variable 'license'.
The catalog information is set using set_byom_catalog() to table_name='byom_models', schema_name='alice', and is used to retrieve the model.
>>> 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'
>>> set_license(license=license, source='string') The license parameters are set. The license is: eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI
>>> df = retrieve_byom('model5', require_license=True)
>>> df model license model_id model5 b'504B03041400080808...' eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI
Example 8: Retrieve a model with license key set at session level by set_license() where license is passed as a file
In this example, retrieve a model with id 'model5' from the table 'byom_models', with license key stored by set_license() in a file.
Since the schema name is not provided, default schema is used.
>>> license_file = os.path.join(os.path.dirname(teradataml.__file__), 'data', 'models', 'License_file.txt')
>>> set_license(license=license_file, source='file') The license parameters are set. The license is: license_string
>>> df = retrieve_byom('model5', table_name='byom_models', require_license=True)
>>> df model license model_id model5 b'504B03041400080808...' license_string
Example 9: Retrieve a model with license key stored in a column of another table set at session level by set_license()
In this example, retrieve a model with id 'licensed_model1' with associated license key stored in the column 'license_key' of the table 'license' present in the schema 'alice'.
The byom catalog and license information is set using set_byom_catalog() and set_license() respectively.
Function is executed with license parameters passed, which overrides the license information set at the session level.
>>> set_byom_catalog(table_name='byom_licensed_models', schema_name='alice') The model cataloging parameters are set to table_name='byom_licensed_models' and schema_name='alice'
>>> set_license(license=license, source='string') The license parameters are set. The license is: eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI
>>> df = retrieve_byom('licensed_model1', license='license_key', is_license_column=True, license_table_name='license')
>>> df model license model_id licensed_model1 b'504B03041400080808...' peBVRtjA-ib
Example 10: Retrieve a model with license key stored in a column of same table set at session level by set_license()
In this example, retrieve a model with id 'licensed_model1' from the table 'byom_licensed_models' with associated license key stored in the column 'license_data' of the table 'byom_licensed_models'.
The byom catalog and license information is already set at the session level, passing the table_name to the function call overrides the byom catalog information at the session level.
>>> 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'
>>> set_license(license='license_data', table_name='byom_licensed_models', schema_name='alice', source='column') The license parameters are set. The license is present in the table='byom_licensed_models', schema='alice' and column='license_data'.
>>> df = retrieve_byom('licensed_model1', table_name='byom_licensed_models', require_license=True)
>>> df model license model_id licensed_model1 b'504B03041400080808...' A5sUL9KU_kP35Vq
>>> df = retrieve_byom('licensed_model1', table_name='byom_licensed_models')
>>> df model model_id licensed_model1 b'504B03041400080808...'