ClariLayer Docs

Getting Started

Overview

Getting Started

Evaluator and design-partner orientation for proving ClariLayer's metric context layer against real workflows.

Use this page when you are evaluating ClariLayer with an existing workspace, a design-partner pilot, or a small internal proof of value. It is intentionally practical: pick one meaningful metric, prove that humans and AI agents can read the same governed context, and avoid broad platform changes until the workflow is trusted.

The evaluator path

Start with a metric that already creates alignment pressure. Good candidates are board-facing revenue metrics, customer health metrics, usage metrics that drive automation, or operational metrics that different teams define differently. A weak candidate is a metric nobody argues about, because there is little context for ClariLayer to preserve.

The goal is not to recreate your entire analytics estate on day one. The goal is to prove that ClariLayer can turn one high-value definition into a governed, versioned, agent-readable asset.

What ClariLayer should own

ClariLayer is the context layer for business metrics. It should own the metric's meaning, owner, lifecycle status, approval evidence, validation evidence, release history, and human reasoning. Warehouses and semantic layers continue to own query execution and runtime consumption.

For the first metric, confirm these facts before you start:

  • The business owner can state what the metric includes and excludes.
  • The current warehouse source is known, even if it is imperfect.
  • The team can identify who approves the definition.
  • At least one downstream consumer cares about the answer, such as a dashboard, AI agent, BI workflow, or operating review.

Warehouse coverage

The shared product path covers catalog browse, validation, direct deployment, and rollback across Databricks, Snowflake, and BigQuery. That means the first evaluation metric can use any of those warehouses for the main define-validate-release path.

Observe and query-history ingest are different. The live Observe ingestion path remains Databricks-only today. If you are evaluating Snowflake or BigQuery, use catalog, validation, deployment, rollback, and API context as the proof points; do not expect Snowflake or BigQuery query-history ingest to appear in Observe yet.

First metric checklist

Work through one metric end to end:

  1. Pick the metric and name the owner.
  2. Capture the business definition, including what is counted, what is excluded, time-window semantics, and caveats.
  3. Validate the SQL or generated logic against the connected warehouse.
  4. Move the metric through the release workflow according to your team's governance rule.
  5. Add Reasoning Trail notes for the decisions, objections, or clarifications that a future analyst or AI agent would need.
  6. Pin only the notes that should become agent-readable context.
  7. Create an API key for the external consumer and read the metric through the v1 API.

This keeps the proof narrow enough to review while still exercising the important workflow: business meaning becomes validated metric context, and the same context is readable by humans and AI agents.

What to pin

Pinned notes should be concise institutional memory, not a transcript. A useful pinned note might say that Finance approved UTC month boundaries for board reporting, that internal test workspaces are excluded, or that an open objection remains about whether free-tier customers should be separated from paid customers.

Use the Reasoning Trail for the broader discussion. Use pinned notes for facts that should travel into agent context. Owners and admins should unpin stale notes when the metric's interpretation changes.

Read the Reasoning Trail concept

API proof

For an API proof, create an API key from the existing workspace settings flow and save the key when it is shown. The full secret is returned once. Current keys created through the API-key route default to the Agent Contract scope pair: canonical-metric-api:read and definition:read.

Use the Metrics List and Detail reference for discovery and detail reads, then use the metrics contract endpoint when an agent, BI workflow, or automation needs the canonical context for one metric.

Then prove three reads:

GET https://app.clarilayer.com/api/v1/metrics?q=revenue
Authorization: Bearer cl_0000000000000000000000000000000000000000
GET https://app.clarilayer.com/api/v1/metrics/5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b
Authorization: Bearer cl_0000000000000000000000000000000000000000
GET https://app.clarilayer.com/api/v1/metrics/5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b/contract
Authorization: Bearer cl_0000000000000000000000000000000000000000

The metric IDs and key above are sample values. Use a real metric ID from your workspace and keep live API keys out of tickets, docs, prompts, and browser recordings.

Evaluation questions

A strong first proof should answer these questions:

  • Can a business owner explain the approved definition without reading SQL?
  • Can a reviewer see the validation and release history?
  • Can an AI agent receive enough context to avoid guessing which definition is canonical?
  • Can the team see why the definition is shaped this way, not just what the current SQL says?
  • Are warehouse boundaries clear, especially the Databricks-only Observe/query-history ingest boundary?

If the answer is yes, the next step is usually to add adjacent metrics in the same domain, then introduce managed variants only where departments legitimately need different definitions.

Useful next pages