Introducing Strata: The Semantic Layer That Keeps Your LLM in Check

Strata is an expressive semantic layer designed to act as a guardrail for Large Language Models, ensuring they don't hallucinate your data logic. You can deploy Strata locally and move from a blank slate to actionable insights in roughly 15 minutes.

🛠️ Prerequisites

Before starting, ensure your environment has the following:

• Docker (Installed and running)
• Ruby $\ge$ 3.4.4
• Git
• Read access to your data warehouse

---

🚀 Getting the Server Running

The Strata server operates within a Docker container and includes its own database, meaning there is zero minimal configuration required.

Option A: The Recommended Installer

Run this command in your terminal. It automatically verifies Docker, pulls the necessary image, and monitors the container until it is healthy.

curl -fsSL https://strata.do/server/install.sh | bash

Press Enter to accept the default port settings.

Option B: Manual Docker Execution

If you prefer a standard docker run command:

docker run -d -p 8080:80 -v strata_data:/data --name strata ghcr.io/stratasite/server:latest

Note: On the first boot, the system takes 30–60 seconds to initialize. Once ready, navigate to http://localhost:8080 to set up your administrator account.

Trial Details: Your free trial activates automatically upon login. To help you get started, a TPC-DS retail sample model is pre-loaded for immediate exploration.

---

💻 CLI Installation & Project Setup

The Command Line Interface (CLI) is the hub for managing warehouse connections, project files, and deployments.

1. Install the CLI:

   curl -fsSL https://strata.do/cli/install.sh | bash
   

2. Verify Installation: strata version

Initializing Your Project

Strata projects are essentially folders of YAML files managed via Git.

strata init my-analytics
cd my-analytics

Each project includes an AGENTS.md file. This file serves as the "instruction manual" for coding agents (like Claude Code or Cursor), explaining exactly how Strata's modeling logic works.

---

🔌 Connecting Your Warehouse

This is the only step requiring your specific network credentials. Strata supports a wide array of data sources:

Setup Process:

1. Run the add command: strata datasource add snowflake (replace snowflake with your provider).
2. The CLI will prompt you for a key (e.g., warehouse), a display name, and the credentials listed above.
3. Credentials are saved in .strata, which is automatically added to .gitignore to ensure security.

Verification:

• Test the connection: strata datasource test warehouse
• List available tables: strata datasource tables warehouse

---

🏗️ Building the Semantic Model

You can build your model using an AI agent or manually via the CLI.

Method 1: Using a Coding Agent (Recommended)

Open your project root in Claude Code, Codex, or Cursor. The agent uses AGENTS.md as a contract to understand naming rules and join constraints.

The Workflow:

1. Request: "Build the semantic model for the tables in my warehouse datasource."
2. Analysis: The agent inspects the schema and proposes facts, dimensions, and joins.
3. Review: You should specifically check:
   • Which tables are designated as Facts vs. Dimensions.
   • Blending: If two tables share the same field name, Strata treats them as the same concept.
   • Role Playing: If a dimension needs multiple keys, a role-playing table is required.
4. Execution: Upon approval, the agent writes to models/**/*.yml and runs strata audit to validate.

Method 2: Manual CLI Construction

If you prefer total control, use the CLI to build one piece at a time:

# Create tables
strata create table sales/orders
strata create table common/customers

# Define the relationship
strata create relation sales/orders_customers

---

🚢 Deployment & Exploration

Once your YAML is ready, validate and push it to the server:

strata audit all
strata deploy

On the first deploy, you will be asked for your server URL (http://localhost:8080) and prompted to sign in via your browser to save an API key.

The Exploration Loop

The power of Strata is realized in the UI:

• Natural Language: Ask questions in plain English; Strata maps them to the correct fields.
• Data Blending: Drag a measure from one fact and a dimension from another. Strata will either blend them or explain why it cannot.
• Reporting: Use the layout engine to arrange views into a cohesive report.
• Cohort Analysis: Add segments to measures to compare cohorts against a baseline.

The Development Lifecycle

The iterative process follows this mathematical logic: $\text{Edit YAML} \rightarrow \text{strata audit all} \rightarrow \text{strata deploy} \rightarrow \text{Insight}$

---

🛠️ Troubleshooting

"The page at localhost:8080 won't load" The bundled database takes 30–60 seconds to start. Check the logs: docker logs -f strata Wait until you see "Databases ready".

"Docker permission denied" or "Not running"

• Ensure Docker Desktop is active.
• If you encounter permission errors, use sudo: curl -fsSL https://strata.do/server/install.sh | sudo bash

"Port 8080 is already in use" Remove the existing container: docker rm -f strata. Re-run the installer and specify a different port, or change the mapping in the manual command (e.g., -p 9090:80).

Container Management:

• Pause/Resume: docker stop strata / docker start strata
• Upgrade: Re-run the installer script.
• Full Reset: docker rm -f strata (Note: Your data persists in the strata_data volume).
• Wipe All Data: docker volume rm strata_data

Uninstalling the CLI: gem uninstall strata-cli and delete your project folder.