Coginiti Projects Reference

A project is a collection of packages, together with their dependencies, that is versioned and released as a unit. Where a package groups blocks, a project groups packages and gives them a shared name, version, and configuration.

Overview

A project is defined by a manifest file named project.toml, written in TOML, placed in the project's root directory. Any catalog folder becomes part of a project when a project.toml exists at or above it: Coginiti determines whether an asset belongs to a project by walking up its parent folders and looking for project.toml.

A typical project lays out packages as subdirectories, with the manifest at the root:

sample_data
├── sales
│   ├── sales_header
│   └── sales_details
├── reports
│   └── summary
└── project.toml

The manifest file

The manifest has one required section, [general], and three optional sections: [dependencies], [environment], and [semantic].

[general]

Holds the project's identity. Only name and version are required; description is optional.

[general]
name = "coginiti.co/foundation/retail"
description = "Ready-to-use retail analytics on sales and customer data."
version = "1.7.5"

• name — the identifier used to refer to the project, both when another project lists it as a dependency and when forming import paths for its packages. The recommended convention starts with a domain name to keep the name globally unique, using / as a separator for further namespacing. In coginiti.co/foundation/retail, coginiti.co is the organization's domain, foundation is a grouping namespace, and retail is the project name.
• version — the project version. Coginiti recommends Semantic Versioning (major.minor.patch): increment major for breaking changes, minor for backward-compatible features, and patch for bug fixes. "latest" is reserved and may not be used as a version value.
• description — a short summary of the project.

[dependencies]

Lists other projects this project depends on. Each entry maps a project name to a specification that uses either a version or a path — not both.

Use version to depend on a project published to the Project Hub:

[dependencies]
"coginiti.co/foundation/retail" = { version = "1.7.5" }

Use "latest" to always reference the most recently published version:

[dependencies]
"coginiti.co/foundation/retail" = { version = "latest" }

Use path to depend on a project that lives elsewhere in your catalog, such as the @Personal or @Shared workspaces:

[dependencies]
"coginiti.co/foundation/retail" = { path = "@Personal/My Projects/retail_foundation" }

[environment]

Defines the connection environments the project can run against. default names the environment to use when none is chosen, and each [environment.<key>] subtable gives a display name and a connection. A connection references a catalog connection by name and may supply overrides (for example, a different schema):

[environment]
default = "dev"

[environment.dev]
name = "Development"
connection = { name = "Dev Connection", overrides = { schema = "dev" } }

[environment.prod]
name = "Production"
connection = { name = "Prod Connection", overrides = { schema = "prod" } }

[semantic]

Defines the semantic models available in the project. default names the one to use when none is chosen, and each [semantic.<key>] subtable gives a display name, a path to the semantic package, and the environment it runs against:

[semantic]
default = "all"

[semantic.all]
name = "Full Data"
path = "semantic/all"
environment = "dev"

[semantic.sales]
name = "Sales Domain"
path = "semantic/sales"
environment = "prod"

Import paths in a project

Within a project, packages are imported by an absolute path that uses the project name as a prefix, followed by the path to the package. Given the project named coginiti.co/sample_data shown above, the reports/summary package imports the sales package like this:

#+import "coginiti.co/sample_data/sales"  -- package from the current project

SELECT * FROM {{ sales.Header() }};

To use a package from another project, add that project to [dependencies] and import it by its project name prefix:

#+import "coginiti.co/foundation/retail/mart"  -- "mart" package from a dependency

SELECT * FROM {{ mart.FactSalesReturn() }};

You can still import a package from a catalog folder that is not part of any project by giving its absolute catalog path:

#+import "@Personal/samples/data"  -- "data" package from a Personal-namespace folder

note

Two projects whose names and package paths overlap can produce an ambiguous import — for example, a sales package inside coginiti.co/foundation/retail collides with the root of a project named coginiti.co/foundation/retail/sales. Coginiti reports the conflict and the projects involved. Resolve it by moving one of the imports into a separate file in the same package, since each file has its own import scope.