Skip to main content
This class is used to interact with a Squirrels project from Python. For example, you can create a SquirrelsProject object in Python (or Jupyter Notebook) as such: 
from squirrels import SquirrelsProject

sqrl = SquirrelsProject(project_path="path/to/squirrels/project/")
And then call methods on the SquirrelsProject object to perform various operations. This class can be imported from the squirrels module.

​
Constructor

Creates a SquirrelsProject object. 
def __init__(
    self, *, project_path: str = ".", load_dotenv_globally: bool = False,
    log_to_file: bool = False, 
    log_level: Literal["DEBUG", "INFO", "WARNING"] = "INFO", 
    log_format: Literal["text", "json"] = "text"
) -> None:

​
Methods

Methods that can be invoked from the SquirrelsProject object.

​
compile()

Async method to compile the SQL templates into files in the “target/” folder. Same functionality as the “sqrl compile” CLI. 
async def compile(
    self, *, selected_model: str | None = None, test_set: str | None = None, 
    do_all_test_sets: bool = False, runquery: bool = False, clear: bool = False, 
    buildtime_only: bool = False, runtime_only: bool = False
) -> None:
​
returns
None
No return value.

​
get_all_data_models()

Async method to list all data models in the project. 
async def get_all_data_models(self) -> list[DataModelItem]:
​
returns
list[DataModelItem]
A list of DataModelItem objects. The DataModelItem object has the following properties:

​
get_all_data_lineage()

Async method to retrieve lineage across models, datasets, and dashboards. 
async def get_all_data_lineage(self) -> list[LineageRelation]:
​
returns
LineageRelation[]
A list of LineageRelation objects. The LineageRelation object has the following properties:

​
seed()

Method to retrieve a seed as a polars LazyFrame given a seed name. 
def seed(self, name: str) -> polars.LazyFrame:
​
returns
polars.LazyFrame
A polars LazyFrame of the seed data.

​
build()

Async method to build the virtual data environment. Same functionality as the “sqrl build” CLI. 
async def build(
  self, *, full_refresh: bool = False, select: str | None = None
) -> None:
​
returns
None
No return value.

​
dataset_metadata()

Method to retrieve the metadata (descriptions, columns, etc.) for a dataset. 
def dataset_metadata(self, name: str) -> DatasetMetadata:
​
returns
DatasetMetadata
A DatasetMetadata object.

​
dataset_result()

Async method to retrieve the dataset result given parameter selections. Unlike the dataset method of DashboardArgs, this method returns a DatasetResult object (which includes metadata) instead of a polars DataFrame. Furthermore, while the DashboardArgs method automatically borrows selections applied to the dashboard, this method requires selections to be explicitly provided through code. 
async def dataset_result(
    self, name: str, *, selections: dict[str, Any] = {}, 
    user: RegisteredUser | None = None, configurables: dict[str, str] = {}
) -> DatasetResult:
​
returns
DatasetResult
A DatasetResult object.

​
dashboard()

Async method to retrieve a dashboard given parameter selections. 
async def dashboard(
    self, name: str, *, selections: dict[str, Any] = {}, 
    user: RegisteredUser | None = None, 
    dashboard_type: type[PngDashboard | HtmlDashboard] = PngDashboard, 
    configurables: dict[str, str] = {}
) -> PngDashboard | HtmlDashboard:
​
returns
PngDashboard | HtmlDashboard
A PngDashboard or HtmlDashboard object based on dashboard_type.

​
query_models()

Async method to query the data models with SQL given parameter selections. 
async def query_models(
    self, sql_query: str, *, selections: dict[str, Any] = {}, 
    user: RegisteredUser | None = None, configurables: dict[str, str] = {}
) -> DatasetResult:
​
returns
DatasetResult
A DatasetResult object.

​
get_compiled_model_query()

Async method to compile a specific data model and return its language and compiled definition. 
async def get_compiled_model_query(
    self, model_name: str, *, selections: dict[str, Any] = {}, 
    user: RegisteredUser | None = None, configurables: dict[str, str] = {}
) -> CompiledQueryModel:
​
returns
CompiledQueryModel
A CompiledQueryModel object with language, definition, and placeholders.

​
get_fastapi_components()

Get the FastAPI components for the Squirrels project including mount path, lifespan, and FastAPI app. 
def get_fastapi_components(
    self, *, no_cache: bool = False, host: str | None = None, port: int | None = None, 
    mount_path_format: str = "/analytics/{project_name}/v{project_version}"
) -> FastAPIComponents:
​
returns
FastAPIComponents
A FastAPIComponents object with properties:
  • mount_path (str): The mount path for the Squirrels project.
  • lifespan (AsyncGeneratorContextManager): The lifespan context manager for the Squirrels project.
  • fastapi_app (FastAPI): The FastAPI app for the Squirrels project.

​
close()

Use this method to deliberately close any database connections opened by the SquirrelsProject object. The database connections may still be opened again by other methods invoked on the SquirrelsProject object after this method is called. 
def close(self) -> None:
​
returns
None
No return value.

​
Examples

Here are some common usage patterns for the SquirrelsProject class. It is assumed that the code is running in an async context (e.g. inside an async function or a Jupyter Notebook cell).

​
Basic project initialization

from squirrels import SquirrelsProject

# Initialize with default settings (current directory)
sqrl = SquirrelsProject()

# Initialize with specific project path
sqrl = SquirrelsProject(project_path="path/to/project")

# Initialize with environment variables and file logging
sqrl = SquirrelsProject(
    project_path="path/to/project",
    log_format="json",
    log_level="DEBUG"
)

​
Compiling and building models

from squirrels import SquirrelsProject

sqrl = SquirrelsProject()

# Compile all models
await sqrl.compile()

# Compile a specific model and print its SQL
await sqrl.compile(selected_model="my_model")

# Compile with a specific test set
await sqrl.compile(test_set="test_set_1")

# Build the virtual data environment
await sqrl.build()

# Full refresh build (drop and rebuild everything)
await sqrl.build(full_refresh=True)

# Build only a specific model
await sqrl.build(select="my_model")

​
Querying a dataset

from squirrels import SquirrelsProject

sqrl = SquirrelsProject()

# Get dataset metadata
metadata = sqrl.dataset_metadata("sales_data")
print(f"Description: {metadata.target_model_config.description}")
print(f"Columns: {[col.name for col in metadata.target_model_config.columns]}")

# Query a dataset with parameter selections
result = await sqrl.dataset_result(
    "sales_data",
    selections={
        "date_range": ["2024-01-01", "2024-12-31"],
        "region": "north-america"
    }
)

# The result.df attribute is a polars DataFrame
print(result.df.head())

# Convert to pandas if needed
pandas_df = result.df.to_pandas()
print(pandas_df.head())

​
Working with authentication

from squirrels import SquirrelsProject
from squirrels.auth import RegisteredUser, CustomUserFields

from pyconfigs.user import CustomUserFields

sqrl = SquirrelsProject()

# Note: CustomUserFields must be extended in your project's user.py
custom_fields = CustomUserFields()  # Use your extended class

# Create a registered user with custom fields
user = RegisteredUser(username="john_doe", custom_fields=custom_fields)

# Query dataset as authenticated user
result = await sqrl.dataset_result(
    "protected_data",
    selections={"year": "2024"},
    user=user
)

# Querying protected datasets with code also allows for bypassing authentication
result = await sqrl.dataset_result(
    "protected_data",
    selections={"year": "2024"}
)

# Access the polars DataFrame
print(result.df)

​
Working with dashboards

Render a PNG dashboard in a Jupyter Notebook: 
from squirrels import SquirrelsProject
from squirrels.dashboards import PngDashboard, HtmlDashboard

sqrl = SquirrelsProject()

# Get a PNG dashboard
png_dashboard = await sqrl.dashboard(
    "sales_overview",
    selections={"quarter": "Q1"},
    dashboard_type=PngDashboard
)
png_dashboard
Render an HTML dashboard in a Jupyter Notebook: 
from squirrels import SquirrelsProject
from squirrels.dashboards import HtmlDashboard

sqrl = SquirrelsProject()

# Get an HTML dashboard
html_dashboard = await sqrl.dashboard(
    "interactive_report",
    selections={"year": "2024"},
    dashboard_type=HtmlDashboard
)
html_dashboard

​
Querying models directly

from squirrels import SquirrelsProject

sqrl = SquirrelsProject()

# Query models using custom SQL
result = await sqrl.query_models(
    "SELECT * FROM my_model WHERE amount > 1000",
    selections={"date_param": "2024-01-01"}
)

# Access the polars DataFrame
print(result.df)

# Get compiled query for a specific model
compiled = await sqrl.get_compiled_model_query(
    "my_model",
    selections={"region": "west"}
)

print(f"Language: {compiled.language}")
print(f"Query:\n{compiled.definition}")

​
Working with seeds

from squirrels import SquirrelsProject

sqrl = SquirrelsProject()

# Get a seed as a polars LazyFrame
seed_lf = sqrl.seed("lookup_table")

# Collect and print the data
df = seed_lf.collect()
print(df)

​
Exploring project metadata

from squirrels import SquirrelsProject

sqrl = SquirrelsProject()

# List all data models
models = await sqrl.get_all_data_models()
for model in models:
    print(f"{model.name} ({model.model_type}): queryable={model.is_queryable}")

# Get data lineage
lineage = await sqrl.get_all_data_lineage()
for relation in lineage:
    print(f"{relation.source.name} ({relation.source.type}) -> "
          f"{relation.target.name} ({relation.target.type}) [{relation.type}]")

​
Close database connections

from squirrels import SquirrelsProject

sqrl = SquirrelsProject()

# Perform operations...

# Close database connections associated with the project when done
sqrl.close()