create_context | Teradata Python Package - 17.00 - create_context - Teradata Package for Python

Teradata® Package for Python User Guide

Product
Teradata Package for Python
Release Number
17.00
Release Date
November 2021
Content Type
User Guide
Publication ID
B700-4006-070K
Language
English (United States)

Use the create_context() function to create a connection to Vantage using the teradatasql and teradatasqlalchemy DBAPI and dialect combination.

You can pass all required arguments (host, username, password) to establish a connection to Vantage, or pass a sqlalchemy engine to the tdsqlengine parameter to override the default DBAPI and dialect combination. You can create connection to Vantage enabled with various security mechanisms.

The optional logdata argument specifies parameters to the LOGMECH command beyond those needed by the logon mechanism, such as user ID, password and tokens (in case of JWT) to successfully authenticate the user.

The optional database argument specifies the initial database to use after log on, instead of your default database.

In case you do not have permissions to create tables or views in your own database, but are allowed to create the required objects in other common database, you must use the argument temp_database_name to pass the name of the other database where temporary tables and views will be created. If this argument is not provided, intermediate database objects are created in your default database.

The temp_database_name and database arguments play a crucial role in determining which database is used by default to lookup for tables and views while creating teradataml DataFrame using 'DataFrame()' and 'DataFrame.from_table()' and which database is used to create all internal temporary objects.
Arguments provided Where the actions are done
temp_database_name database Internal temporary objects are created in Database object (table or view) lookup is done from
Yes Yes temp_database_name database
No Yes database database
Yes No temp_database_name User's default database
No No User's default database User's default database
teradataml requires that the user has certain permissions on the user's default database or the initial default database specified using database, or the temporary database specified using temp_database_name.

These permissions allow the user to:

  • Create tables and views to save results of teradataml analytic functions;
  • Create views in the background for results of DataFrame APIs such as 'assign()', 'filter()', etc., whenever the result for these APIs are accessed using a 'print()';
  • Create views in the background on the query passed to the 'DataFrame.from_query()' API.

It is expected that the user has the correct permissions to create these objects in the database to be used.

The access to the views created may also require issuing additional GRANT SELECT ... WITH GRANT OPTION permission depending on which database is used and which object the view being created is based on.

Passwords passed as part of either password or logdata argument can be in encrypted format using Stored Password Protection.

Examples section below demonstrates passing encrypted password to the password argument.

For more information on Stored Password Protection and how to generate key and encrypted password file used in examples, see the Stored Password Protection section under the teradatasql project, on https://pypi.org/user/teradata/.

When overwriting an existing context associated with a Vantage connection, most of the operations on any teradataml DataFrames created before will not work.
Teradata recommends calling remove_context() to end a session, so that intermediate views and tables created by teradataml are garbage collected.
Executing create_context() triggers garbage collection in teradataml.

See Garbage Collection in teradataml for more details.

teradataml expects the client environments are already setup with appropriate security mechanisms and are in working conditions.

For more information, see Teradata Vantage™ - Advanced SQL Engine Security Administration.

Example: Create a context using hostname, username and password

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword')

Example: Create a context using already created sqlalchemy engine

>>> from sqlalchemy import create_engine
>>> sqlalchemy_engine  = create_engine('teradatasql://'+ tduser +':' + tdpassword + '@'+tdhost
>>> from teradataml.context.context import *
>>> create_context(tdsqlengine = sqlalchemy_engine)

Example: Create a context with default logmech 'TD2'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='TD2')

Example: Create a context with default logmech 'TDNEGO'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='TDNEGO')

Example: Create a context with default logmech 'LDAP'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='LDAP')

Example: Create a context with default logmech 'KRB5'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', logmech='KRB5')

Example: Create a context with default logmech 'JWT'

You must use the 'logdata' argument when using 'JWT' as logon mechanism.
>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', logmech='JWT', logdata='token=eyJpc...h8dA')

Example: Create a context using encrypted password and key passed to the 'password' argument

Specify the password in the following format:
ENCRYPTED_PASSWORD(file:<PasswordEncryptionKeyFileName>, file:<EncryptedPasswordFileName>)
Where:
  • PasswordEncryptionKeyFileName specifies the name of a file that contains the password encryption key and associated information
  • EncryptedPasswordFileName specifies the name of a file that contains the encrypted password and associated information.
Each filename must be preceded by the 'file:' prefix. The PasswordEncryptionKeyFileName must be separated from the EncryptedPasswordFileName by a single comma.
>>> td_context = create_context(host = 'tdhost', username='tduser', password = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)")

Example: Create a context using encrypted password in LDAP logon mechanism

>>> td_context = create_context(host = 'tdhost', username='tduser', password = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)", logmech='LDAP')

Example: Create a context to connect to a different initial database, using hostname, username and password

This example creates a context using hostname, username and password, and connect to a different initial database by setting the database argument.

>>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', database = 'database_name')

Example: Creates a context to connect to a different initial database, using already created sqlalchemy engine

This example creates a context using already created sqlalchemy engine, and connect to a different initial database by setting the database argument.

>>> from sqlalchemy import create_engine
>>> sqlalchemy_engine  = create_engine('teradatasql://'+ tduser +':' + tdpassword + '@'+tdhost + '/?DATABASE=database_name')
>>> create_context(tdsqlengine = sqlalchemy_engine)

Example: Create a context to connect to a different initial database, using 'LDAP' logmech

This example creates a context with 'LDAP' logmech, and connect to a different initial database by setting the database argument.

>>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='LDAP', database = 'database_name')