Skip to main content

Trilogy Projects

Trilogy Projects

Goals

Trilogy aims to be relatively unopinionated about how files have to be laid out.

Convention can minimize surprise, and so if there is no reason to default from suggestions, it's recommended to follow.

The most important file on disk is the trilogy.toml used for default resolution.

A Good Default

A default layout is the following - the CLI will generally default to this unless otherwise specified.

  • /assets/root subfolder for base tables
  • /derived subfolder for derived assets
  • /jobs subfolder for update jobs, such as persist or append into derived assets
  • trilogy.toml base config file with default engines, startup scripts, etc.

trilogy.toml Configuration

trilogy.toml uses standard TOML syntax. Strings are quoted, booleans are written as true or false, and repeated values such as setup scripts are arrays. Paths in setup, engine.env_file, and local database locations are resolved relative to the directory that contains the TOML file.

CLI flags and command arguments take precedence over values in trilogy.toml, so the file is best used for project defaults.

# Trilogy Configuration File
# Learn more at: https://github.com/trilogy-data/pytrilogy

# Max parallelism for multi-file directory execution.
parallelism = 4

[project]
name = "analytics"

[engine]
# Default dialect for commands that execute against a backend.
# Common values include duckdb, sqlite, postgres, snowflake,
# sql_server, presto, and bigquery.
dialect = "duckdb"

# Optional .env file or files to load before execution.
env_file = [".env"]

[engine.config]
# Dialect-specific connection options.
# For duckdb and sqlite, db_location is resolved relative to this file.
db_location = "local.duckdb"
enable_python_datasources = true
enable_gcs = false
enable_spatial = false

[setup]
# Startup scripts run before the target file or directory.
trilogy = ["setup/model.preql"]
sql = ["setup/setup_dev.sql"]

[staging]
# Optional local path, gs:// URI, or s3:// URI for temporary files.
path = ".trilogy/staging"

[serve]
studio_url = "https://trilogydata.dev/trilogy-studio-core/"

[agent]
provider = "openai"
model = "gpt-4.1"
api_key_env = "OPENAI_API_KEY"
max_iterations = 50
tool_output_limit = 8192

Common dialect-specific engine.config keys:

  • duck_db: db_location or path, enable_python_datasources, enable_gcs, enable_spatial
  • sqlite: db_location or path
  • postgres: host, port, username, password, database
  • snowflake: account, username, password, database, schema
  • sql_server: host, port, username, password, database
  • presto: host, port, username, password, catalog, schema
  • bigquery: project