Analyst Manual Overview
Welcome to the Olytix Core Analyst Manual. This comprehensive guide covers everything data analysts need to build, maintain, and optimize semantic layer implementations.
What This Manual Covers
This manual is organized into logical sections that follow the data modeling lifecycle:
Core Concepts
Understand the foundational concepts that power Olytix Core:
- Unified Project — How sources, models, cubes, and metrics connect
- Dependency Graph — Understanding the DAG and execution order
- Compilation Process — From YAML to executable queries
- Lineage Basics — Column-level tracking from source to metric
Data Modeling
Build your semantic layer from the ground up:
Sources
- Defining data sources
- Freshness monitoring
- Schema documentation
Models
- SQL transformations with Jinja
- Materialization strategies
- Incremental models and snapshots
Cubes
- Cube fundamentals
- Measures and dimensions
- Joins and relationships
- Pre-aggregations for performance
Metrics
- Simple, derived, and ratio metrics
- Metric filters
- Time intelligence
Querying
Execute queries against your semantic layer:
- Semantic query syntax
- Filters and operators
- Time dimensions
- Query optimization
- Async and streaming queries
Time Intelligence
Implement time-based analytics:
- Period-to-date calculations
- Period comparisons
- Rolling windows
- Fiscal calendars
- Timezone handling
Lineage
Track data flow through your system:
- Column-level lineage
- Upstream and downstream analysis
- Impact analysis
- Measure and metric lineage
Testing
Ensure data quality:
- Data tests
- Schema tests
- Custom tests
- CI/CD integration
The Data Flow
Understanding how data flows through Olytix Core is essential:
┌─────────────────────────────────────────────────────────────────────┐
│ Olytix Core Data Flow │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ External Data │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Databases │ │ APIs │ │ Files │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └─────────────┼─────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Sources │ Define connections │
│ │ (YAML) │ Document schema │
│ └───────┬───────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Models │ Transform data │
│ │ (SQL+Jinja) │ Clean and join │
│ └───────┬───────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Cubes │ Define semantics │
│ │ (YAML) │ Measures + Dimensions │
│ └───────┬───────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Metrics │ Business KPIs │
│ │ (YAML) │ Time intelligence │
│ └───────┬───────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ API │ REST / GraphQL / DAX │
│ │ │ Query engine │
│ └───────┬───────┘ │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Dashboards│ │ Python │ │ BI Tools │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Key Concepts Quick Reference
| Concept | Description | Example |
|---|---|---|
| Source | External data connection | source('raw', 'orders') |
| Model | SQL transformation | SELECT * FROM {{ ref('stg_orders') }} |
| Cube | Semantic definition | Measures, dimensions, joins |
| Measure | Numeric aggregation | SUM(amount), COUNT(*) |
| Dimension | Categorical attribute | Region, status, date |
| Metric | Business KPI | Monthly revenue, churn rate |
| Lineage | Data flow tracking | Source → Model → Cube → Metric |
Building Your First Semantic Layer
Here's a typical workflow for building a semantic layer:
1. Define Sources
Tell Olytix Core where your data lives:
sources:
- name: raw
tables:
- name: orders
- name: customers
2. Create Models
Transform raw data into analytics-ready tables:
-- models/fct_orders.sql
SELECT
order_id,
customer_id,
SUM(amount) AS total_amount
FROM {{ source('raw', 'orders') }}
GROUP BY order_id, customer_id
3. Define Cubes
Create semantic layer abstractions:
cubes:
- name: orders
sql: "SELECT * FROM {{ ref('fct_orders') }}"
measures:
- name: total_revenue
type: sum
sql: total_amount
dimensions:
- name: order_date
type: time
sql: order_date
4. Create Metrics
Define business KPIs:
metrics:
- name: monthly_revenue
expression: orders.total_revenue
time_grain: month
5. Query via API
Access your semantic layer:
{
"metrics": ["monthly_revenue"],
"dimensions": ["orders.order_date.month"]
}
Best Practices at a Glance
Naming Conventions
| Type | Convention | Example |
|---|---|---|
| Source | Descriptive name | raw, salesforce, stripe |
| Staging model | stg_<source>_<table> | stg_raw_orders |
| Fact model | fct_<entity> | fct_orders |
| Dimension model | dim_<entity> | dim_customers |
| Cube | Singular noun | orders, customer |
| Measure | Action + noun | total_revenue, count_orders |
| Metric | Descriptive | monthly_revenue, customer_churn_rate |
Project Organization
my_project/
├── sources/
│ └── raw.yml # Source definitions
├── models/
│ ├── staging/ # Source cleaning
│ ├── intermediate/ # Complex transforms
│ └── marts/ # Final tables
├── cubes/
│ └── orders.yml # Semantic definitions
├── metrics/
│ └── revenue.yml # Business metrics
└── tests/
└── data_quality.yml # Quality tests
Documentation
Always document your assets:
- name: monthly_revenue
description: |
## Definition
Monthly net revenue after refunds.
## Calculation
SUM(net_amount) WHERE status = 'completed'
## Owner
Finance Team
Common Tasks
| Task | Location |
|---|---|
| Connect to a new data source | Defining Sources |
| Create a SQL transformation | Model Basics |
| Define a new measure | Measures |
| Add time-based analysis | Time Intelligence |
| Track data lineage | Column-Level Lineage |
| Set up data tests | Data Tests |
Getting Help
- FAQ — Common questions answered
- Troubleshooting — Solutions to common issues
- Glossary — Term definitions
Next Steps
Ready to start building? Begin with:
- Core Concepts → — Understand the fundamentals
- Defining Sources → — Connect your data
- Cube Fundamentals → — Build your semantic layer