teradataml.catalog.byom.retrieve_byom = retrieve_byom(model_id, table_name, schema_name=None, license=None, is_license_column=False, license_table_name=None, license_schema_name=None)

DESCRIPTION:
    Function to retrieve a saved model. Output of this function can be
    directly passed as input to the PMMLPredict and H2OPredict functions.
    Some models generated, such as H2O-DAI has license associated with it.
    When such models are to be used for scoring, one must retrieve the model
    by passing relevant license information. Please refer to "license_key"
    for more details.
 
PARAMETERS:
    model_id:
        Required Argument.
        Specifies the unique model identifier of the model to be retrieved.
        Types: str
 
    table_name:
        Required Argument.
        Specifies the name of the table to retrieve external model from.
        Types: str
 
    schema_name:
        Optional Argument.
        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 current schema.
        Types: str
 
    license:
        Optional Argument.
        Specifies the license key information in different ways specified as below:
        * If the license key is stored in a variable, user can pass it as string.
        * If the license key is stored in table, then pass a column name containing
          the license. Based on the table which has license information stored,
            * If the information is stored in the same model table as that of the
              model, one must set "is_license_column" to True.
            * If the information is stored in the different table from that of the
              "table_name", one can specify the table name and schema name using
              "license_table_name" and "license_schema_name" respectively.
        Types: str
 
    is_license_column:
        Optional Argument.
        Specifies whether license key specified in "license" is a license key
        or column name. When set to True, "license" contains the column name
        containing license data, otherwise contains the actual license key.
        Default Value: False
        Types: str
 
    license_table_name:
        Optional Argument.
        Specifies the name of the table which holds license key. One can specify this
        argument if license is stored in a table other than "table_name".
        Types: str
 
    license_schema_name:
        Optional Argument.
        Specifies the name of the Database associated with the "license_table_name".
        If not specified, current Database would be considered for "license_table_name".
        Types: str
 
RETURNS:
    teradataml DataFrame
 
RAISES:
    TeradataMlException, TypeError
 
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, retrieve_byom, get_context
    >>> save_byom('model5', model_file, 'byom_models')
    Model is saved.
    >>> save_byom('model6', model_file, 'byom_models', schema_name='test')
    Model is saved.
    >>> 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 the license in a table.
    >>> license = 'eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI'
    >>> 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>
    >>>
 
    # Example 1 - Retrieve a model with id 'model5' from the table 'byom_models'.
    >>> df = retrieve_byom('model5', table_name='byom_models')
    >>> df
                                 model
    model_id
    model5    b'504B03041400080808...'
 
    # Example 2 - Retrieve a model with id 'model6' from the table 'byom_models'
    #             and the table is in '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 with id 'model5' from the table 'byom_models'
    #             with license key stored in a variable 'license'.
    >>> df = retrieve_byom('model5', table_name='byom_models', license=license)
    >>> df
                                 model                                                         license
    model_id
    model5    b'504B03041400080808...'  eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI
    >>>
 
    # Example 4 - Retrieve a model with id 'licensed_model1' and associated license
    #             key stored in table 'byom_licensed_models'. License key is stored
    #             in 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 with id 'licensed_model1' from the table
    #             'byom_licensed_models' and associated license key stored in
    #             column 'license_key' of the 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 with id 'licensed_model1' from the table
    #             'byom_licensed_models' and associated license key stored in
    #             column 'license_key' of the table 'license' present in the
    #             schema 'mldb'.
    >>> 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
    >>>