Configuration options
Pixeltable can be configured through:- Environment variables
- System configuration file (
~/.pixeltable/config.tomlon Linux/macOS orC:\Users\<username>\.pixeltable\config.tomlon Windows) pxt.init(), for the calling process only:pxt.init({'openai.api_key': '...'})
file_cache_size_g and file_cache_lease_s.
Prefer environment variable names (
PIXELTABLE_API_KEY, PIXELTABLE_OUTPUT_MEDIA_DEST). Pixeltable resolves environment variables from the process environment and never loads a .env file itself, so source one yourself first (set -a; source .env; set +a) or load it with a dotenv library. Provider keys go under Secrets or pxt secret. On a hosted Cloud database the home bucket is already the default media store; dest env vars are for local Pixeltable and bring-your-own buckets. See Cloud storage.config.toml:
System settings
Per-database settings
Media destinations and the OTLP endpoint and protocol can also be set for a single database. Each database has a[[pixeltable.database]] entry in pixeltable.toml. Add a db_<key> field to that entry to set <key> for that
database only. A [[pixeltable.database]] entry with no name corresponds to the local database. A
[[pixeltable.database]] entry named pxt://org:db is a hosted database, and must be in pixeltable.toml, not
config.toml. Its pods read the entry and the sections of
pixeltable.toml after pxt db update, and pxt service update restarts running services with them. For a hosted
database, pxt db update refuses a secret in pixeltable.toml (a key named api_key, api_secret, api_token,
token, storage_account_key, or exporter_otlp_headers); set it with
pxt secret set pxt://org:db OPENAI_API_KEY=... instead.
- Database entry:
db_<key>in[[pixeltable.database]] - Environment variable: the variable from the table above, or a
pxt.init()override - Global config:
<key>under[pixeltable]/[otel]inconfig.toml, shared by every database on the installation - Fallback: a hosted database uses its home bucket for media
db_exporter_otlp_endpoint and db_exporter_otlp_protocol. It sends its telemetry to the collector in the pod, at the address in the pod’s environment.
The OTLP auth headers are a secret and do not go in the entry: set OTEL_EXPORTER_OTLP_HEADERS in the environment, and on a hosted database with pxt secret set pxt://org:db OTEL_EXPORTER_OTLP_HEADERS=... (see pxt secret).
Telemetry from a hosted database
Each pod of a hosted database runs an OpenTelemetry Collector. Pixeltable in the pod sends its traces, metrics, and logs to that collector, and the collector sends them to your OTLP backends. The first backend takes its endpoint and protocol from the database’s entry (db_exporter_otlp_endpoint, db_exporter_otlp_protocol), or else from the secrets OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_PROTOCOL. Its headers come from the secret OTEL_EXPORTER_OTLP_HEADERS. Secrets whose names start with OTEL_EXPORTER_OTLP_ or OTEL_TRACES_SAMPLER_ARG go only to the collector, so that Pixeltable in the pod keeps sending its telemetry to the collector.
Each further backend is a set of secrets whose names end in __<NAME>:
OTEL_TRACES_SAMPLER_ARG to a ratio between 0 and 1 to change that share, or OTEL_TRACES_SAMPLER_ARG__<NAME> for one backend. Logs and metrics are sent in full.
The collector also sends traces to CloudWatch, sampled the same way. OTEL_TRACES_SAMPLER_ARG__CLOUDWATCH sets the share of the other traces that CloudWatch keeps. Without it, OTEL_TRACES_SAMPLER_ARG sets that share, and the default is 10%. You cannot name a backend CLOUDWATCH. Read the spans with pxt db spans and pxt service spans.
The pods read these settings at startup. The endpoint and protocol in the entry reach the pods with the project files, so after you change them, run pxt db update and then pxt service update. After you change a secret, run pxt db restart and pxt service restart.
API configuration
Rate limit configuration
Pixeltable supports two patterns for configuring API rate limits inconfig.toml. Refer to the docstring of the
relevant udf in the SDK Reference for details on the rate limiting pattern used by that udf.
Single rate limit per provider
For providers with a single rate limit across all models, add arate_limit key to the provider’s config section:
Per-model rate limits
For providers that support different rate limits for different models, add a<provider>.rate_limits section and list the rate limits for each model:
. or :. Otherwise TOML reads . as a nested key, and : is a syntax error.
If no rate limit is configured, Pixeltable uses a default of 600 requests per minute.
Configuration best practices
Security considerations
When configuring API keys and sensitive information:- Avoid hardcoding API keys in your code
- Use environment variables for temporary access
- Use the config file for persistent configuration
- Ensure your config.toml file has appropriate permissions (readable only by you)
Performance tuning
- Adjust
file_cache_size_gbased on your available system memory - For large datasets, increase the cache size to improve performance
- Set appropriate verbosity level based on your debugging needs
Applying configuration changes
Configuration changes take effect when you restart your Python session.Installation Guide
Return to the installation guide for setup instructions