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

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:
        Optional Argument.
        Specifies the name of the table to retrieve external model from.
        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 retrieve_byom() take precedence and is used for
                function execution.
        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 retrieve_byom() take precedence and is used for
                function execution.
            * If user specifies schema_name argument table_name argument has to be specified,
                else exception is raised.
        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
 
    require_license:
        Optional Argument.
        Specifies whether the model to be retrieved is associated with a license.
        If True, license information set by the set_license() is retrieved.
        Note:
            If license parameters are passed, then this argument is ignored.
        Default value: False
        Types: bool
 
    return_addition_columns:
        Optional Argument.
        Specifies whether to return additional columns saved during save_byom() along with
        model_id and model columns.
        Default value: False
        Types: bool
 
    Note:
        The following table describes the system behaviour in different scenarios:
        +----------------+-------------+-----------------------+-------------+-------------------------------------+
        |       In retrieve_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      |
        |                |             |                       |             |  retrieve_byom() are used for       |
        |                |             |                       |             |  function execution.                |
        +----------------+-------------+-----------------------+-------------+-------------------------------------+
        | Set            | Set         | Not set               | Not set     |  schema_name and table_name in      |
        |                |             |                       |             |  retrieve_byom() is used for        |
        |                |             |                       |             |  function execution.                |
        +----------------+-------------+-----------------------+-------------+-------------------------------------+
        | Not set        | Not set     | Set                   | Set         |  table_name from retrieve_byom()    |
        |                |             |                       |             |  is used and schema name            |
        |                |             |                       |             |  associated with the current        |
        |                |             |                       |             |  context is used.                   |
        +----------------+-------------+-----------------------+-------------+-------------------------------------+
        | Not set        | Set         | Set                   | Set         |  Exception is raised.               |
        +----------------+-------------+-----------------------+-------------+-------------------------------------+
        | Not set        | Not set     | Set                   | Set         |  table_name and schema_name         |
        |                |             |                       |             |  from set_byom_catalog()            |
        |                |             |                       |             |  are used for function execution.   |
        +----------------+-------------+-----------------------+-------------+-------------------------------------+
        | Not set        | Not set     | 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     | Not set               | Not set     |  Exception is raised                |
        +----------------+-------------+-----------------------+-------------+-------------------------------------+
 
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 the license in an addtional column named "license_data" in the model table.
    >>> 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);'
    >>> execute_sql(lic_table)
    <sqlalchemy.engine.cursor.LegacyCursorResult object at 0x0000014AAFF27080>
    >>> execute_sql("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
    >>>
 
    # Example 7 - 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'
    #             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 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 id 'licensed_model1' and associated license
    #             key stored in 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 id 'licensed_model1' from the table
    #              'byom_licensed_models' and associated license key stored in
    #              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
 
    # Example 11 - If require license=False which is the default value for the above example,
    #              the license information is not retrieved.
    >>> df = retrieve_byom('licensed_model1', table_name='byom_licensed_models')
    >>> df
                                        model
    model_id
    licensed_model1  b'504B03041400080808...'
 
    # Example 12 - Retrieve a model with id 'licensed_model1' from the table along with all
    #              additional columns saved during save_byom().
    >>> df = retrieve_byom('licensed_model1', table_name='byom_licensed_models',
                           return_addition_columns=True)
    >>> df
                                        model     license_data
    model_id
    licensed_model1  b'504B03041400080808...'  A5sUL9KU_kP35Vq