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

Teradata® Package for Python User Guide

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
VMware
Product
Teradata Package for Python
Release Number
20.00
Published
March 2024
Language
English (United States)
Last Update
2024-04-09
dita:mapPath
nvi1706202040305.ditamap
dita:ditavalPath
plt1683835213376.ditaval
dita:id
rkb1531260709148
Product Category
Teradata Vantage

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.

The following examples section 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™ - Analytics Database Security Administration.

Special characters that may be used in the password are encoded by default. The encoding is done using urllib.parse library and can be disabled by setting the optional argument url_encode to False. For example, if the password is: "kx%jj5/g", then this password is encoded as "kx%25jj5%2Fg", where, '%25' represents the '%' character and '%2F' represents the '/' character. Details of how the special characters are replaced can be found on the URL escape codes page.
When password contains space:
  • The space must not be encoded.
  • Optional argument url_encode must be set to False.
  • All other special characters, if present in this password, must be manually encoded, following the URL escape codes.

See example 16 for a detailed demonstration.

When password contains unreserved characters like tilde ("~"), dot ("."), underscore ("_"), hyphen ("-"):
  • Unreserved characters are not URL encoded by default.
  • If unreserved character in the password needs to be encoded, it must be encoded manually encoded and encoded password must be passed along with optional argument url_encode set to False.
  • Unreserved characters differ in different Python versions.

    For example, the encoding standards for Python version 3.7 can be found in the following link: https://docs.python.org/3/library/urllib.parse.html#url-quoting.

    Teradata recommends checking the encoding standards for your Python version before manual encoding special characters.

Example 1: Create a context using hostname, username and password

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

Example 2: 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 3: Create a context with default logmech 'TD2'

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

Example 4: Create a context with default logmech 'TDNEGO'

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

Example 5: Create a context with default logmech 'LDAP'

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

Example 6: Create a context with default logmech 'KRB5'

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

Example 7: 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 8: 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 9: 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 10: 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 11: 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 12: 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')

Example 13: Create a context using 'tera' mode

This example creates a context using 'tera' mode with log value set to 8 and lob_support disabled.

>>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', tmode = 'tera', log = 8, lob_support = False)

Example 14: Create a context when password contains special characters

This example creates a context when password has special characters, and the example password "alice@pass" is encoded by default.

>>> td_context = create_context(host = 'tdhost', username='alice_pass', password = 'alice@pass')
UserWarning: Warning: Password is URL encoded.

Example 15: Create a context when password contains space and special characters

This example creates a context with password containing space and special characters.

In this scenario, optional argument url_encode must be set to 'False' and special characters must be manually encoded.

For example, if the password is: "kx%jj5/ g", then this password is encoded as "kx%25jj5%2F g".

Where,
  • '%25' represents the '%' character
  • '%2F' represents the '/' character
  • Space is not encoded
>>> td_context = create_context(host = 'tdhost', username='alice_pass', password = 'kx%25jj5%2F g', url_encode=False)