Skip to main content

Quickstart

Quickstart

Choose an entrypoint into Trilogy:

CLI demo

Trilogy includes a public model registry with prebuilt models to help you get started on the data work fast. In this demo, you'll fetch an FAA flight model, query and chart it, build a derived datasource, and open the same project in Studio.

1. Install and fetch a model

Install Trilogy with terminal charting and the local Studio server:

pip install --upgrade "pytrilogy[cli,serve]>=0.3.371"

See Installation for other installation options. You'll need internet access to fetch the model, query its hosted data, and load Studio.

trilogy public fetch faa ./faa-demo
cd faa-demo

This downloads the model's source .preql files, examples, supporting scripts, and trilogy.toml. The project configuration selects DuckDB, so you can run the rest of the commands from faa-demo without specifying an engine.

2. Query and explore flights

Count flights by carrier:

trilogy run --import flight "select carrier.code, count(id) as flight_count order by flight_count desc;"

--import flight prepends the model import for you. Trilogy uses the model to find the data and joins, so your query only needs to name the concepts you want. The result lists carrier codes and their flight counts, largest first.

To discover the concepts available for your own queries:

trilogy explore flight.preql

3. Plot the busiest carriers

Use the same model to draw a horizontal bar chart of the top ten carriers in your terminal:

trilogy run --import flight "chart layer barh ( y_axis <- carrier.name, x_axis <- count(id) as flight_count ) order by flight_count desc limit 10;"

4. Build a derived datasource

The fetched project uses an in-memory database by default. Before building an asset, add a database path to trilogy.toml so the table survives between commands and is available when you open Studio. The complete configuration should be:

[engine]
dialect = "duck_db"

[engine.config]
path = "faa.duckdb"

Fetch the hosted reporting example into a new file:

trilogy file write reporting.preql --from-url https://raw.githubusercontent.com/trilogy-data/trilogy-public-models/refs/heads/main/examples/duckdb/faa/example.preql

The script imports the flight model, defines a flight date and flight count, and declares a daily_airplane_usage datasource grouped by date and aircraft model. Build that managed asset with:

trilogy refresh reporting.preql

The first refresh creates daily_airplane_usage in faa.duckdb. Later refreshes check the model and watermarks to decide whether the asset needs rebuilding.

The CLI may also report stale imported assets from the public model. This command builds the local reporting table using the hosted data; it does not require refreshing those public sources. You can edit reporting.preql and rerun the command to rebuild your table.

5. Explore in Studio

Launch Studio against your local project to explore the model and run queries in the browser:

trilogy serve .

This starts the local model server and opens Studio in your browser. Keep the terminal running while you use Studio; press Ctrl+C to stop the server.

Keep going