Environment variables¶

Every tdfs4ds setting can be supplied through an OS environment variable named TDFS4DS_<VAR_NAME>. This channel is the canonical way to inject secrets in CI/CD pipelines.

Teradata connection (TD_*) and Vector Store auth (VECTOR_STORE_AUTH_*) variables are pass-through vars — read directly from os.environ, not module config — documented in Connecting and Deployment rather than in the matrix below.

Variable matrix¶

Variable	Setting
`TDFS4DS_SCHEMA`	`tdfs4ds.SCHEMA` (database for tables)
`TDFS4DS_SCHEMA_VIEW`	`tdfs4ds.SCHEMA_VIEW` (optional database for views; blank = same as `SCHEMA`)
`TDFS4DS_SCHEMA_READONLY`	`tdfs4ds.SCHEMA_READONLY` (optional comma-separated list of OTHER feature stores to read from; blank = none)
`TDFS4DS_DATA_DOMAIN`	`tdfs4ds.DATA_DOMAIN`
`TDFS4DS_DISPLAY_LOGS`	`tdfs4ds.DISPLAY_LOGS`
`TDFS4DS_LOG_COLOR`	`tdfs4ds.LOG_COLOR` (blank / `auto` = colour log lines by level in a notebook or a colour terminal; `true` / `false` to force; `NO_COLOR` also turns it off)
`TDFS4DS_LOG_PROPAGATE`	`tdfs4ds.LOG_PROPAGATE` (default `false`: tdfs4ds prints its own lines on stdout; `true` = send them to your application's root logging instead, nothing printed by tdfs4ds)
`TDFS4DS_DEBUG_MODE`	`tdfs4ds.DEBUG_MODE`
`TDFS4DS_QUERY_BAND`	`tdfs4ds.QUERY_BAND` (default `true`: tag each process execution with a session query band, for the follow-up ↔ DBQL join)
`TDFS4DS_EXECUTION_RESOURCES`	`tdfs4ds.EXECUTION_RESOURCES` (default `true`: keep each execution's DBQL figures in `FS_EXECUTION_RESOURCES` / `FS_EXECUTION_STATEMENTS`, beyond DBQL's retention)
`TDFS4DS_AGENTIC_FEATURES`	`tdfs4ds.AGENTIC_FEATURES` (default `true`; `false` turns off every AI step of `upload_features` that the call does not pass explicitly)
`TDFS4DS_UPLOAD_DOCUMENT`	`tdfs4ds.UPLOAD_DOCUMENT` (default `true`): default of `upload_features(document=)`
`TDFS4DS_UPLOAD_EXPLAIN`	`tdfs4ds.UPLOAD_EXPLAIN` (default `true`): default of `upload_features(explain=)`, the LLM analysis of the EXPLAIN plan during documentation
`TDFS4DS_UPLOAD_OPTIMIZE_QUERY`	`tdfs4ds.UPLOAD_OPTIMIZE_QUERY` (default `false`): default of `upload_features(optimize_query=)`
`TDFS4DS_UPLOAD_VECTOR_INDEXING`	`tdfs4ds.UPLOAD_VECTOR_INDEXING` (default `false`): default of `upload_features(vector_indexing=)`
`TDFS4DS_UPLOAD_CASCADE_REDOCUMENTATION`	`tdfs4ds.UPLOAD_CASCADE_REDOCUMENTATION` (default `false`): default of `upload_features(cascade_redocumentation=)`
`TDFS4DS_STORE_FEATURE`	`tdfs4ds.STORE_FEATURE` (keep `MERGE`: `UPDATE_INSERT` is broken)
`TDFS4DS_REGISTER_FEATURE` / `TDFS4DS_REGISTER_PROCESS`	`tdfs4ds.REGISTER_FEATURE` / `REGISTER_PROCESS` (default `MERGE`): how a feature / process catalog row is written
`TDFS4DS_VARCHAR_SIZE`	`tdfs4ds.VARCHAR_SIZE`
`TDFS4DS_FEATURE_PARTITION_N` / `TDFS4DS_FEATURE_PARTITION_EACH`	`tdfs4ds.FEATURE_PARTITION_N` / `FEATURE_PARTITION_EACH` (default `20000` / `1`): the `RANGE_N(FEATURE_ID BETWEEN 0 AND N EACH E)` partitioning of new storage tables
`TDFS4DS_FEATURE_STORE_TIME`	`tdfs4ds.FEATURE_STORE_TIME`
`TDFS4DS_TIME_MANAGER_CHECK`	`tdfs4ds.TIME_MANAGER_CHECK` (default `warn`): a TimeManager passed to `run` / `roll_out` / `upload_features` that the process view does not read is a warning, refused (`error`) or not checked (`off`)
`TDFS4DS_TIME_MANAGER_DETECT`	`tdfs4ds.TIME_MANAGER_DETECT` (default `true`, 0.3.6.0): `upload_features` without `time_manager=` records the TimeManager the view reads (the data domain's clock gets a soft clone); `false` = record nothing until a `roll_out`, as before 0.3.6.0
`TDFS4DS_PROCESS_SQL_VERSIONING`	`tdfs4ds.PROCESS_SQL_VERSIONING` (default `true`): keep the SQL beneath each process view and its versions in `FS_PROCESS_SQL`; `false` = nothing captured
`TDFS4DS_EXPOSED_VIEW_AUTO_ATTACH`	`tdfs4ds.EXPOSED_VIEW_AUTO_ATTACH` (default `true`): a view exposing a documented table takes the table's documentation during the documentation walk
`TDFS4DS_CREDENTIAL_RENEWAL_ATTEMPTS`	`tdfs4ds.CREDENTIAL_RENEWAL_ATTEMPTS` (default `3`): prompts for a renewed LLM token when one expires during a run; `0` = never ask
`TDFS4DS_INSTRUCT_MODEL_PROVIDER`	`tdfs4ds.INSTRUCT_MODEL_PROVIDER`
`TDFS4DS_INSTRUCT_MODEL_MODEL`	`tdfs4ds.INSTRUCT_MODEL_MODEL`
`TDFS4DS_INSTRUCT_MODEL_URL`	`tdfs4ds.INSTRUCT_MODEL_URL`
`TDFS4DS_INSTRUCT_MODEL_API_KEY`	`tdfs4ds.INSTRUCT_MODEL_API_KEY`
`TDFS4DS_INSTRUCT_MODEL_REGION`	`tdfs4ds.INSTRUCT_MODEL_REGION` (AWS region for Bedrock)
`TDFS4DS_INSTRUCT_MODEL_CLIENT_MODE` / `TDFS4DS_EMBEDDING_MODEL_CLIENT_MODE`	`tdfs4ds.INSTRUCT_MODEL_CLIENT_MODE` / `EMBEDDING_MODEL_CLIENT_MODE` (`ambient` = sign Bedrock OpenAI-endpoint requests with the environment's AWS identity instead of an API key; the embedding one falls back to the instruct one)
`TDFS4DS_INSTRUCT_MODEL_AZURE_DEPLOYMENT` / `_AZURE_API_VERSION`	`tdfs4ds.INSTRUCT_MODEL_AZURE_DEPLOYMENT` / `_AZURE_API_VERSION`
`TDFS4DS_INSTRUCT_MODEL_GCP_PROJECT` / `_GCP_LOCATION`	`tdfs4ds.INSTRUCT_MODEL_GCP_PROJECT` / `_GCP_LOCATION`
`TDFS4DS_EMBEDDING_MODEL_REGION`, `_AZURE_DEPLOYMENT`, `_AZURE_API_VERSION`, `_GCP_PROJECT`, `_GCP_LOCATION`	the matching `tdfs4ds.EMBEDDING_MODEL_` (each falls back to the `INSTRUCT_MODEL_` value)
`TDFS4DS_EMBEDDING_MODEL_PROVIDER`	`tdfs4ds.EMBEDDING_MODEL_PROVIDER`
`TDFS4DS_EMBEDDING_MODEL_MODEL`	`tdfs4ds.EMBEDDING_MODEL_MODEL`
`TDFS4DS_EMBEDDING_MODEL_URL`	`tdfs4ds.EMBEDDING_MODEL_URL`
`TDFS4DS_EMBEDDING_MODEL_API_KEY`	`tdfs4ds.EMBEDDING_MODEL_API_KEY`
`TDFS4DS_EMBEDDING_MODEL_DIM`	`tdfs4ds.EMBEDDING_MODEL_DIM`
`TDFS4DS_EMBEDDING_MODEL_MAX_TOKENS`	`tdfs4ds.EMBEDDING_MODEL_MAX_TOKENS` (default `450`): longer texts are truncated before embedding
`TDFS4DS_EMBEDDING_BATCH_SIZE` / `TDFS4DS_EMBEDDING_BATCH_DELAY`	`tdfs4ds.EMBEDDING_BATCH_SIZE` / `EMBEDDING_BATCH_DELAY` (default `8` documents per call / `0` seconds between calls; set a delay for a small vLLM/TEI server)
`TDFS4DS_INSTRUCT_MODEL_PROXY` / `TDFS4DS_EMBEDDING_MODEL_PROXY`	`tdfs4ds.INSTRUCT_MODEL_PROXY` / `EMBEDDING_MODEL_PROXY`: outbound proxy for the LLM / embedding calls (`http://host:3128` or `socks5://host:1080`; the embedding one falls back to the instruct one)
`TDFS4DS_MCP_SERVER_EDITION`	`tdfs4ds.MCP_SERVER_EDITION` (`community` default, or `enterprise`: credentials are sent, a different tool set)
`TDFS4DS_MCP_SERVER_TRANSPORT`	`tdfs4ds.MCP_SERVER_TRANSPORT` (`streamable_http` default, or `sse`)
`TDFS4DS_MCP_AUTH` / `TDFS4DS_MCP_USERNAME`	`tdfs4ds.MCP_AUTH` / `MCP_USERNAME`: authentication override and user for an Enterprise server (the password is `TDFS4DS_MCP_PASSWORD`, a credential)
`TDFS4DS_MCP_SERVER_CA_BUNDLE`	`tdfs4ds.MCP_SERVER_CA_BUNDLE`: PEM file trusted for the MCP server's certificate (verification stays on)
`TDFS4DS_MCP_MAX_TOOLS` / `TDFS4DS_MCP_FALLBACK_MAX_TOOLS`	`tdfs4ds.MCP_MAX_TOOLS` / `MCP_FALLBACK_MAX_TOOLS` (default `32` / `8`): tools bound to the model per question, and after a context-window error; `0` = no cap
`TDFS4DS_MCP_TOOL_DISCOVERY`	`tdfs4ds.MCP_TOOL_DISCOVERY` (default `true`): on a context-window error, ask the model which tools it needs and retry once
`TDFS4DS_CHROMA_MODE`	`tdfs4ds.CHROMA_MODE`
`TDFS4DS_CHROMA_PATH`	`tdfs4ds.CHROMA_PATH`
`TDFS4DS_CHROMA_HOST`	`tdfs4ds.CHROMA_HOST`
`TDFS4DS_CHROMA_PORT`	`tdfs4ds.CHROMA_PORT`
`TDFS4DS_VECTOR_STORE_BACKEND`	`tdfs4ds.VECTOR_STORE_BACKEND` (`'chroma'`\|`'teradata'`)
`TDFS4DS_TERADATA_VECTOR_STORE_PREFIX`	`tdfs4ds.TERADATA_VECTOR_STORE_PREFIX`
`TDFS4DS_TERADATA_AI_API_TYPE`	`tdfs4ds.TERADATA_AI_API_TYPE`
`TDFS4DS_TERADATA_AI_MODEL_NAME`	`tdfs4ds.TERADATA_AI_MODEL_NAME`
`TDFS4DS_TERADATA_AI_REGION`	`tdfs4ds.TERADATA_AI_REGION`
`TDFS4DS_TERADATA_AI_API_BASE`	`tdfs4ds.TERADATA_AI_API_BASE`
`TDFS4DS_TERADATA_AI_ACCESS_KEY`	`tdfs4ds.TERADATA_AI_ACCESS_KEY` (credential — `.env` / env var only)
`TDFS4DS_QUERY_OPTIMIZER_MAX_CANDIDATES`	`tdfs4ds.QUERY_OPTIMIZER_MAX_CANDIDATES`
`TDFS4DS_QUERY_OPTIMIZER_MAX_FAILURES`	`tdfs4ds.QUERY_OPTIMIZER_MAX_FAILURES`
`TDFS4DS_QUERY_OPTIMIZER_MAX_REFINE_ROUNDS`	`tdfs4ds.QUERY_OPTIMIZER_MAX_REFINE_ROUNDS`
`TDFS4DS_QUERY_OPTIMIZER_REPORT_DIR`	`tdfs4ds.QUERY_OPTIMIZER_REPORT_DIR`
`TDFS4DS_SCHEDULING_MAX_WORKERS`	`tdfs4ds.SCHEDULING_MAX_WORKERS` (default cap on parallel processes per wave in a generated execution script; blank = unbounded)
`TDFS4DS_TRACING`	`tdfs4ds.TRACING` (blank = off; `opik` = trace agent turns with Opik, `pip install tdfs4ds[opik]`; destination = Opik's own configuration)
`TDFS4DS_OPIK_PROJECT_NAME`	`tdfs4ds.OPIK_PROJECT_NAME` (default `tdfs4ds`)
`TDFS4DS_OPIK_VENDOR_TELEMETRY`	`tdfs4ds.OPIK_VENDOR_TELEMETRY` (default `false`: the Opik SDK's analytics and Sentry reports are switched off when tracing starts)
`TDFS4DS_SERVE_DEFAULT_VIEW`	read by the admin app only: first view of a new visitor, `admin` (default) or `user`
`TDFS4DS_SERVE_MCP_URL`	read by the admin app only: a local MCP server started with it (`launch_app(mcp=True)` sets it). Applied after the app's `.env`, so it wins over `TDFS4DS_MCP_SERVER_URL`

Changing one variable¶

tdfs4ds.patch_dotenv(path, {...}) edits a single variable in an existing .env without rewriting the file — see Programmatic globals. check_configuration(pin=True) uses it to record what it probes.

Type coercion¶

Values are parsed at import time:

true / false / 1 / 0 → bool for DISPLAY_LOGS, DEBUG_MODE, etc.
Numeric strings → int for VARCHAR_SIZE, EMBEDDING_MODEL_DIM, CHROMA_PORT, …
Everything else → str

None is encoded as an empty value.

CI/CD recipe¶

# GitHub Actions
env:
  TDFS4DS_SCHEMA: ${{ vars.TDFS4DS_SCHEMA }}
  TDFS4DS_DATA_DOMAIN: ${{ vars.TDFS4DS_DATA_DOMAIN }}
  TDFS4DS_INSTRUCT_MODEL_PROVIDER: openai
  TDFS4DS_INSTRUCT_MODEL_API_KEY: ${{ secrets.OPENAI_API_KEY }}