Programmatic globals¶

The most direct way to configure tdfs4ds is to assign module globals after import. Programmatic assignment always wins over .env, JSON, and OS env vars.

Core settings¶

tdfs4ds.SCHEMA                = 'my_database'        # target database for TABLES (auto-set from context)
tdfs4ds.SCHEMA_VIEW           = None                 # optional database for VIEWS (None = same as SCHEMA); resolve via tdfs4ds.view_schema()
tdfs4ds.FEATURE_STORE_TIME    = None                 # None = current; '2024-01-01 00:00:00' = time travel
tdfs4ds.DISPLAY_LOGS          = True                 # verbose logging gate
tdfs4ds.LOG_COLOR             = None                 # None = colour by level when the output shows colours; True / False to force
tdfs4ds.configure_logging(propagate=True)            # send tdfs4ds lines to your own logging (root handlers) instead of stdout
tdfs4ds.DEBUG_MODE            = False
tdfs4ds.STORE_FEATURE         = 'MERGE'              # 'MERGE' or 'UPDATE_INSERT'
tdfs4ds.VARCHAR_SIZE          = 1024                 # default VARCHAR width for new columns
tdfs4ds.USE_VOLATILE_TABLE    = True                 # use volatile staging tables during ingestion
tdfs4ds.BUILD_DATASET_AT_UPLOAD = False              # auto-build dataset view inside upload_features

Use tdfs4ds.create_data_domain('NAME') (or select_data_domain) instead of setting tdfs4ds.DATA_DOMAIN directly — the helpers validate the domain exists and emit a log.

GenAI / LLM¶

tdfs4ds.INSTRUCT_MODEL_PROVIDER = 'openai'           # 'openai' | 'azure' | 'vllm' | 'bedrock'
tdfs4ds.INSTRUCT_MODEL_MODEL    = 'gpt-4o'
tdfs4ds.INSTRUCT_MODEL_URL      = None                # required for 'vllm' / 'azure'
tdfs4ds.INSTRUCT_MODEL_API_KEY  = 'sk-...'           # prefer .env / env var
tdfs4ds.INSTRUCT_MODEL_TIMEOUT     = 60
tdfs4ds.INSTRUCT_MODEL_MAX_RETRIES = 3

Embeddings + vector store¶

tdfs4ds.EMBEDDING_MODEL_PROVIDER = 'vllm'             # falls back to INSTRUCT_MODEL_* when None
tdfs4ds.EMBEDDING_MODEL_URL      = 'https://api.example.com/v1/e5'
tdfs4ds.EMBEDDING_MODEL_API_KEY  = None
tdfs4ds.EMBEDDING_MODEL_MODEL    = 'text-embedding-3-small'
tdfs4ds.EMBEDDING_MODEL_DIM      = 1536

# Vector store backend
tdfs4ds.VECTOR_STORE_BACKEND         = 'chroma'        # 'chroma' (default) | 'teradata'
tdfs4ds.TERADATA_VECTOR_STORE_PREFIX = 'tdfs4ds'       # base name for the 3 Teradata stores

# Chroma (when VECTOR_STORE_BACKEND='chroma')
tdfs4ds.CHROMA_MODE = 'local'                          # 'local' or 'server'
tdfs4ds.CHROMA_PATH = './tdfs4ds_chroma'               # persist directory (local)
tdfs4ds.CHROMA_HOST = 'localhost'                      # server mode
tdfs4ds.CHROMA_PORT = 8000                             # server mode

# TeradataAI in-database embedding — opt-in when VECTOR_STORE_BACKEND='teradata'.
# Leave TERADATA_AI_API_TYPE = None to keep using the LangChain EMBEDDING_MODEL_*
# settings above (vLLM / TEI / OpenAI-compatible work unchanged).
tdfs4ds.TERADATA_AI_API_TYPE   = None                  # 'aws'|'azure'|'gcp'|'nim'|'hugging_face'|'onnx'
tdfs4ds.TERADATA_AI_MODEL_NAME = None
tdfs4ds.TERADATA_AI_REGION     = None                  # aws
tdfs4ds.TERADATA_AI_API_BASE   = None                  # nim
tdfs4ds.TERADATA_AI_ACCESS_KEY = None                  # credential (prefer .env / env var)

See LLM & embedding models for full examples of both backends.

Query optimizer¶

tdfs4ds.QUERY_OPTIMIZER_MAX_CANDIDATES       = 10
tdfs4ds.QUERY_OPTIMIZER_MAX_FAILURES         = 10
tdfs4ds.QUERY_OPTIMIZER_MAX_REFINE_ROUNDS    = 3
tdfs4ds.QUERY_OPTIMIZER_MAX_CANDIDATE_TOKENS = None    # cap output tokens for small-context models
tdfs4ds.QUERY_OPTIMIZER_REPORT_DIR           = 'tdfs4ds_optim_reports'

Reports are stored under {REPORT_DIR}/{DATA_DOMAIN}/tdfs4ds_optim_<view>_<process_id>.md.

Catalog names¶

tdfs4ds.FEATURE_CATALOG_NAME      = 'FS_FEATURE_CATALOG'
tdfs4ds.PROCESS_CATALOG_NAME      = 'FS_PROCESS_CATALOG'
tdfs4ds.DATASET_CATALOG_NAME      = 'FS_DATASET'
tdfs4ds.DATA_DISTRIBUTION_NAME    = 'FS_DATA_DISTRIBUTION'
tdfs4ds.FOLLOW_UP_NAME            = 'FS_FOLLOW_UP'
tdfs4ds.FILTER_MANAGER_NAME       = 'FS_FILTER_MANAGER'

Set these before the first setup() call. Renaming after deployment is not supported.

Inspecting current values¶

[v for v in dir(tdfs4ds) if v.isupper()]

Changing one variable in an existing `.env`¶

export_config and generate_ai_studio_env both rewrite a .env whole, which loses its comments, its ordering and any commented-out alternatives it carries. patch_dotenv changes one line instead:

tdfs4ds.patch_dotenv('.env', {'STRUCTURED_OUTPUT_METHOD': 'function_calling'},
                     comment='pinned after probing gw.example on 2026-09-11')
# {'updated': ['TDFS4DS_STRUCTURED_OUTPUT_METHOD'], 'added': [], 'unchanged': []}

Which line it touches, and why:

the last uncommented occurrence — the loader assigns as it reads, so on a duplicate the last one is what takes effect; changing any other would leave the file saying one thing and meaning another;
otherwise the first commented-out slot (#TDFS4DS_X=), uncommented in place, since a generated file offers those precisely so that turning one on is an edit;
otherwise appended.

A commented slot is never enabled while a live line exists — a generated file carries commented alternatives next to the live choice, and switching to one of those silently would be the wrong thing entirely.

The comment is written as a trailing note on the line itself, so re-running replaces it rather than stacking a new one; it is dropped for a value that has to be quoted, because the parser reads a quoted value verbatim. Values are rendered the way the loader reads them back, so None becomes the literal None and loads as None — the right way to say "this gateway needs no API key", and distinguishable from nobody having filled it in.

Credentials are refused unless you pass allow_secrets=True: a general-purpose file patcher should not be how a password ends up in a file someone later commits. A name that is not a tdfs4ds variable is refused too, since writing it would only produce an "unknown .env variable" warning on load.