Skip to main content

Documentation Index

Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt

Use this file to discover all available pages before exploring further.

The oxy build command processes your semantic layer (views and topics) and generates embeddings for vector search. It features an intelligent incremental build system that provides 10-100x speedup for small changes.

​
Quick start

# Build semantic layer (incremental by default)
oxy build

# Force full rebuild and clear cache
oxy build --force

​
Build modes

The command automatically determines the most efficient build mode based on what has changed:

​
Incremental build (default)

Only rebuilds changed views/topics and their dependencies. This is ~50x faster for single view changes. 
oxy build
Example output: 
🔧 Incremental build: 2 views, 0 topics
   - orders.view.yml (modified)
   - shipments.view.yml (dependency)
💾 Saving to cube directory...
🎉 Incremental build completed successfully!
When it runs:
  • Files in semantics/views/*.view.yml have changed
  • Files in semantics/topics/*.topic.yml have changed
  • A previous build manifest exists
What it does:
  • Compares current file hashes with previous build
  • Identifies modified, added, or deleted files
  • Automatically rebuilds dependent views (e.g., if view B references view A’s entity)
  • Preserves semantic layer cache for faster startup

​
No-op build (nothing changed)

Skips the build entirely when no changes are detected. Provides instant feedback (~100ms). 
oxy build
Example output: 
✅ No changes detected, semantic layer is up to date
When it runs:
  • No semantic files have changed
  • Database configuration hasn’t changed
  • Global settings haven’t changed

​
Full rebuild

Rebuilds all views and topics from scratch. Clears the semantic layer cache when using --force. 
oxy build --force
# or
oxy build -f
Example output: 
🔨 Full rebuild required: Forced rebuild (--force flag)
🔄 Processing semantic layer...
📂 Loading semantic layer from: semantics
✅ Successfully loaded semantic layer with 12 views
💾 Saving to cube directory...
🎉 Semantic layer processing completed successfully!
When it runs:
  • --force flag is used
  • No previous build manifest exists (first build)
  • Database configuration has changed
  • Global settings have changed

​
Command options

​
—force, -f

Force a complete rebuild and clear the semantic layer cache. 
oxy build --force
oxy build -f
Use this when:
  • After database schema migrations
  • When troubleshooting semantic layer issues
  • When you want a clean slate

​
How it works

​
Build manifest

The incremental build system maintains a manifest file at .semantics/.build_manifest.json that tracks:
  • File hashes: SHA256 hashes of all semantic files
  • Output mappings: Which semantic layer files were generated from which source files
  • Dependency graph: Relationships between views (e.g., foreign key references)
  • Configuration hashes: Database config and global settings for change detection

​
Change detection

On each build:
  1. Scan semantics/views/ and semantics/topics/ directories
  2. Hash all .view.yml and .topic.yml files using SHA256
  3. Compare with previous build manifest
  4. Detect added, modified, and deleted files
  5. Expand dependencies using the view relationship graph
  6. Rebuild only affected views/topics

​
Dependency tracking

Views can depend on other views through entity relationships: 
# customers.view.yml
entity:
  name: customer
  key: customer_id

---
# orders.view.yml
dimensions:
  - name: customer_id
    type: string
    sql: customer_id
    # This creates a dependency: orders → customers
When you modify customers.view.yml, the incremental build automatically rebuilds orders.view.yml as well.

​
Cache preservation

The incremental build preserves the semantic layer cache to avoid expensive schema recompilation:
  • Incremental builds: Cache is preserved
  • Natural full rebuilds: Cache is preserved (config/globals change)
  • Forced rebuilds: Cache is cleared with --force flag

​
Performance benchmarks

For a large semantic layer with 50+ views:
ScenarioBeforeAfterSpeedup
No changes~10s~100ms100x
1 view changed~10s~200ms50x
5 views changed~10s~1s10x
Full rebuild~10s~10s1x

​
Embedding management

oxy build also generates embeddings for vector search. Models are downloaded from Hugging Face Hub, so you may need to authenticate: 
huggingface-cli login
Or copy your token directly: 
echo "your_token" > $HOME/.cache/huggingface/token
After building, verify embeddings: 
oxy vec-search "Hello Embedding"

​
Troubleshooting

​
Build manifest corruption

If the build manifest becomes corrupted, the system automatically falls back to a full rebuild: 
⚠️  Warning: Build manifest is corrupted or invalid
🔨 Full rebuild required: Missing or invalid build manifest

​
Stale cache after manual edits

If you manually edit files in .semantics/model/, the cache may become stale: 
# Clear the cache and rebuild
oxy build --force

​
Dependencies not rebuilding

If dependent views aren’t rebuilding when they should, ensure your entity relationships are properly defined: 
# ✅ Correct: dimension name matches entity key
entity:
  name: customer
  key: customer_id  # References dimension name

dimensions:
  - name: customer_id  # Matches entity key
    type: string

# ❌ Incorrect: entity key references column name
entity:
  name: customer
  key: Customer  # References SQL column, not dimension

​
After database migrations

Always run a full rebuild after changing your database schema: 
oxy build --force

​
Known limitations

  1. Concurrent builds: Not supported. Running multiple oxy build commands simultaneously may cause corruption.
  2. Manual .semantics/ edits: Overwritten on next build (expected behavior).
  3. Database schema changes: Not automatically detected. Use oxy build --force after migrations.
  4. Cross-view SQL references: Not detected if not using entity relationships. Best practice: use entity relationships instead of raw SQL joins.
  • oxy sync - Sync database schema information
  • oxy start - Start infrastructure services and web server
  • oxy vec-search - Search the vector store