Frequently Asked Questions

For Everyone

This page answers the most common questions about Olytix Core. If you do not find your answer here, check the Troubleshooting guide or reach out to the community.

General Questions

What is Olytix Core?

Olytix Core (Unified Analytics Modeling Platform) is an enterprise-grade headless analytics platform that combines data transformation capabilities (similar to dbt) with semantic layer functionality (similar to Cube). It provides a single source of truth for your metrics and enables consistent analytics across all your BI tools.

How is Olytix Core different from using dbt + Cube together?

While you can use dbt and Cube together, this approach has several drawbacks:

Challenge	dbt + Cube	Olytix Core
Metadata sync	Manual synchronization	Automatic, unified
Lineage	Separate, disconnected	End-to-end, column-level
Deployment	Two separate pipelines	Single deployment
Testing	Separate test suites	Unified testing

Olytix Core provides true unification, not just integration.

Is Olytix Core compatible with my existing dbt project?

Yes. Olytix Core uses dbt-compatible syntax for models:

Same ref() and source() functions
Same materialization types (view, table, incremental)
Same Jinja templating
Same project structure conventions

Most dbt projects can be migrated with minimal changes. See the Migration from dbt guide.

What databases does Olytix Core support?

Olytix Core supports major cloud data warehouses and databases:

PostgreSQL
Snowflake
BigQuery
Databricks
Amazon Redshift
DuckDB

Can I use Olytix Core with my existing BI tools?

Yes. Olytix Core is headless and API-first, meaning it works with any BI tool that can consume REST APIs or SQL:

Power BI: Native DAX/XMLA support
Tableau: REST API or direct SQL
Looker Studio: REST API integration
Metabase: Direct database connection
Python/Jupyter: REST API or Python client

Installation and Setup

What are the system requirements?

Python 3.11 or later
2GB RAM minimum (4GB+ recommended)
PostgreSQL, Snowflake, BigQuery, or other supported warehouse

How do I install Olytix Core?

pip install olytix-core
olytix-core --version

For development installations:

pip install -e ".[dev]"

How do I configure database connections?

Configure connections in olytix-core_project.yml:

name: my_project
version: 1.0.0

warehouse:
  type: postgresql
  host: localhost
  port: 5432
  database: analytics
  user: ${OLYTIX_DB_USER}
  password: ${OLYTIX_DB_PASSWORD}

Use environment variables for sensitive values:

export OLYTIX_DB_USER=your_username
export OLYTIX_DB_PASSWORD=your_password

How do I start the API server?

# Compile your project first
olytix-core compile

# Start the server
olytix-core serve

The API will be available at http://localhost:8000.

Semantic Layer

What is a semantic layer?

A semantic layer is an abstraction that sits between your raw data and your BI tools. It defines:

Measures: Aggregations like SUM(revenue) or COUNT(orders)
Dimensions: Attributes for filtering and grouping
Metrics: Business KPIs built on measures
Joins: Relationships between entities

This ensures everyone in your organization uses the same definitions.

What is the difference between a measure and a metric?

Measure: A low-level aggregation defined within a cube (e.g., sum(amount))
Metric: A higher-level business definition that may combine measures (e.g., "Monthly Revenue" or "Customer Lifetime Value")

# Measure (in a cube)
measures:
  - name: total_revenue
    type: sum
    sql: amount

# Metric (standalone)
metrics:
  - name: monthly_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: month

When should I use pre-aggregations?

Use pre-aggregations when:

Queries are slow (taking more than a few seconds)
You have predictable query patterns
You need to support high concurrency
You want to reduce warehouse costs

pre_aggregations:
  - name: monthly_revenue
    measures: [total_revenue]
    dimensions: [country]
    time_dimension: order_date
    granularity: month
    refresh:
      cron: "0 2 * * *"

How do joins work in Olytix Core?

Joins connect cubes to enable multi-entity queries:

cubes:
  - name: orders
    joins:
      - name: customers
        relationship: many_to_one
        sql: "{orders}.customer_id = {customers}.customer_id"

Olytix Core automatically handles join paths when you query across cubes.

Data Modeling

How do I reference other models?

Use the ref() function:

SELECT *
FROM {{ ref('stg_orders') }}

How do I reference source tables?

Use the source() function:

SELECT *
FROM {{ source('raw', 'orders') }}

What materializations are available?

Type	Description	Use Case
`view`	Database view	Simple transformations
`table`	Physical table	Complex aggregations
`incremental`	Append-only updates	Large fact tables
`ephemeral`	Inline CTE	Intermediate steps

How do I create an incremental model?

{{ config(
    materialized='incremental',
    unique_key='order_id'
) }}

SELECT *
FROM {{ source('raw', 'orders') }}
{% if is_incremental() %}
WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
{% endif %}

Querying

How do I query the semantic layer?

Use the REST API:

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["total_revenue"],
    "dimensions": ["order_date.month", "country"]
  }'

Can I see the generated SQL?

Yes. Include include_sql: true in your request or check the response metadata:

{
  "data": [...],
  "query": {
    "sql": "SELECT DATE_TRUNC('month', order_date)...",
    "duration_ms": 45
  }
}

How do I filter queries?

Use the filters parameter:

{
  "metrics": ["total_revenue"],
  "dimensions": ["country"],
  "filters": [
    {
      "dimension": "order_date.year",
      "operator": "equals",
      "value": 2024
    },
    {
      "dimension": "status",
      "operator": "in",
      "values": ["completed", "shipped"]
    }
  ]
}

Lineage

What is column-level lineage?

Column-level lineage tracks how individual columns flow through your entire data pipeline:

Source Column     ->  Model Column      ->  Measure        ->  Metric
raw.orders.amount ->  fct_orders.total  ->  orders.revenue ->  monthly_revenue

How do I view lineage?

Use the API:

# Upstream lineage (what feeds into this column)
curl http://localhost:8000/api/v1/lineage/upstream/orders.total_revenue

# Downstream lineage (what this column feeds)
curl http://localhost:8000/api/v1/lineage/downstream/raw.orders.amount

How do I perform impact analysis?

curl http://localhost:8000/api/v1/lineage/impact/raw.orders.amount

This shows all downstream artifacts that would be affected if you changed the source column.

Performance

Why are my queries slow?

Common causes:

No pre-aggregations: Create pre-aggregations for common query patterns
Large joins: Ensure proper indexing and consider denormalization
Complex calculations: Move heavy calculations to models
Missing indexes: Add indexes to frequently filtered columns

How can I optimize query performance?

Use pre-aggregations for common query patterns
Materialize models as tables for complex transformations
Filter early in your model SQL
Use incremental models for large datasets
Monitor with EXPLAIN to identify bottlenecks

Security

Does Olytix Core support row-level security?

Yes. Define security policies:

security:
  row_level:
    - name: region_filter
      cube: orders
      condition: "{region} = {{user.region}}"

How do I set up authentication?

Olytix Core supports multiple authentication methods:

API keys
JWT tokens
OAuth 2.0 (via integration)

Configure in olytix-core_project.yml or via environment variables.

Troubleshooting

Where can I find error logs?

Check the server logs or use:

olytix-core compile --verbose
olytix-core serve --log-level debug

My changes are not reflected in queries

Recompile the project: olytix-core compile
Restart the server: Ctrl+C and olytix-core serve
Clear pre-aggregation cache if applicable

I am getting a "model not found" error

Verify the model file exists and has the correct extension (.sql)
Check for typos in ref() calls
Run olytix-core compile and check for errors

For more solutions, see the Troubleshooting guide.

Getting Help

Documentation: You're here
Troubleshooting: Common issues and solutions
Glossary: Term definitions

General Questions​

What is Olytix Core?​

How is Olytix Core different from using dbt + Cube together?​

Is Olytix Core compatible with my existing dbt project?​

What databases does Olytix Core support?​

Can I use Olytix Core with my existing BI tools?​

Installation and Setup​

What are the system requirements?​

How do I install Olytix Core?​

How do I configure database connections?​

How do I start the API server?​

Semantic Layer​

What is a semantic layer?​

What is the difference between a measure and a metric?​

When should I use pre-aggregations?​

How do joins work in Olytix Core?​

Data Modeling​

How do I reference other models?​

How do I reference source tables?​

What materializations are available?​

How do I create an incremental model?​

Querying​

How do I query the semantic layer?​

Can I see the generated SQL?​

How do I filter queries?​

Lineage​

What is column-level lineage?​

How do I view lineage?​

How do I perform impact analysis?​

Performance​

Why are my queries slow?​

How can I optimize query performance?​

Security​

Does Olytix Core support row-level security?​

How do I set up authentication?​

Troubleshooting​

Where can I find error logs?​

My changes are not reflected in queries​

I am getting a "model not found" error​

Getting Help​