> ## Documentation Index
> Fetch the complete documentation index at: https://docs.5x.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Cube Playground
> Master the Cube Playground interface for building queries, defining cube schemas, and exploring your data
**Focus:** Learn how to use the Cube Playground to visually build queries, write SQL, define cube schemas, and explore your data interactively.
The Cube Playground is an interactive development environment embedded in the Metrics Store that provides a visual interface for building queries, defining cube schemas, and exploring your data. It's powered by Cube.js and integrated seamlessly with the 5X platform.
## Accessing Cube Playground
### **Prerequisites**
Before accessing Cube Playground:
1. **Select a project** - Choose an active Cube project
2. **Select a branch** - Choose a branch to work with
## Cube Playground interface
### **Main components**
The Cube Playground interface includes:
**Query builder**
* Visual drag-and-drop interface for building queries
* Select measures and dimensions from available cubes
* Apply filters and configure aggregations
* Preview query results
**SQL editor**
* Direct SQL query execution
* Syntax highlighting and autocomplete
* Query history and saved queries
* Execute and test queries
**Schema explorer**
* Browse available cubes, measures, and dimensions
* View cube definitions and metadata
* Understand data structure and relationships
* Navigate hierarchical cube organization
**Query results**
* Display query results in tables or charts
* Export results to various formats
* Analyze data patterns and insights
**Schema files**
* Edit cube definitions using YAML or JavaScript
* Version-controlled schema files
* Deploy and test schema changes
## Building queries
### **Visual query builder**
Use the visual query builder to create queries without writing SQL:
1. **Select cube**
* Choose a cube from the sidebar
* View available measures and dimensions
2. **Choose measures**
* Select quantitative metrics to calculate
* Examples: revenue, orders, users, conversions
* Can select multiple measures
3. **Add dimensions**
* Select attributes for grouping and analysis
* Examples: date, region, product category
* Can add multiple dimensions
4. **Apply filters**
* Filter data by specific values or ranges
* Date range filters
* Categorical filters
* Numeric filters
5. **Configure aggregations**
* Set time granularity (day, week, month, etc.)
* Configure sorting and ordering
* Set result limits
6. **Execute query**
* Click **"Run"** to execute the query
* View results in the results panel
* Export or save query if needed
### **SQL editor**
Write SQL queries directly for advanced use cases:
1. **Open SQL editor**
* Switch to SQL editor tab
* Write SQL queries using Cube.js SQL syntax
2. **Query syntax**
```sql theme={null}
SELECT
orders.status,
orders.total_revenue
FROM orders
WHERE orders.created_at >= '2024-01-01'
GROUP BY orders.status
ORDER BY orders.total_revenue DESC
```
3. **Execute and test**
* Click **"Run"** to execute
* Review results and query performance
* Iterate and refine queries
4. **Save queries**
* Save frequently used queries
* Share queries with team members
* Build query library
## Defining cubes
### **Cube schema structure**
Cubes are defined using YAML or JavaScript schema files:
```yaml theme={null}
cubes:
- name: orders
sql_table: orders
measures:
- name: count
type: count
- name: total_revenue
sql: sum(amount)
type: sum
- name: average_order_value
sql: sum(amount) / count(*)
type: number
dimensions:
- name: status
sql: status
type: string
- name: created_at
sql: created_at
type: time
- name: customer_id
sql: customer_id
type: string
primary_key: true
```
### **Schema components**
**Measures**
* Quantitative metrics and calculations
* Types: count, sum, avg, min, max, number
* Custom SQL expressions
* Aggregation functions
**Dimensions**
* Attributes for analysis and grouping
* Types: string, number, time, boolean
* Primary keys for joins
* Hierarchical relationships
**Time dimensions**
* Special dimensions for time-based analysis
* Support for time grains (day, week, month, etc.)
* Built-in time intelligence functions
* Period-over-period comparisons
### **Editing schemas**
1. **Access schema files**
* Navigate to schema files in Cube Playground
* Edit YAML or JavaScript files directly
2. **Make changes**
* Add new cubes, measures, or dimensions
* Modify existing definitions
* Update SQL expressions
3. **Save and deploy**
* Save schema changes
* Deploy to make changes available
* Changes take effect immediately
4. **Test changes**
* Test queries in Playground
* Verify results are correct
* Iterate and refine
## Exploring data
### **Schema explorer**
Browse your cube structure:
1. **View cubes**
* See all available cubes in sidebar
* Navigate cube hierarchy
* Understand cube relationships
2. **Explore measures**
* View available measures per cube
* Understand measure definitions
* See measure types and calculations
3. **Explore dimensions**
* View available dimensions per cube
* Understand dimension types
* See dimension relationships
### **Data preview**
Preview actual data:
1. **Sample data**
* View sample data from cubes
* Understand data structure
* Verify data quality
2. **Query results**
* Execute queries and view results
* Analyze data patterns
* Export results for further analysis
## Best practices
### **Query building**
**Build incrementally**
Start with basic queries and add complexity gradually. Test each step before adding more measures or dimensions.
**Limit data scope**
Apply filters to reduce data volume and improve query performance. Filter early in your query building process.
**Validate before deploying**
Always test queries in Cube Playground before using them in production dashboards or applications.
**Add comments**
Document complex queries with comments explaining business logic and calculations.
### **Schema development**
* **Version control** - Commit schema changes regularly with descriptive messages
* **Incremental changes** - Make small, testable changes rather than large refactors
* **Documentation** - Add descriptions and examples to cube definitions
* **Testing** - Test schema changes thoroughly before deploying
* **Review** - Use pull requests for schema changes in protected branches
### **Performance optimization**
* **Efficient measures** - Use appropriate aggregation types
* **Indexed dimensions** - Ensure frequently used dimensions are indexed
* **Query optimization** - Review query performance and optimize slow queries
* **Data filtering** - Apply filters to reduce data volume
* **Caching** - Leverage Cube.js caching for frequently accessed data
## Troubleshooting
### **Common issues**
**Possible causes:**
* Heartbeat status not RUNNING
* Project not selected
* Branch not selected
* Network connectivity issues
**Solutions:**
* Check heartbeat status indicator
* Verify project and branch are selected
* Wait for server to start (check deployment options)
* Refresh the page
* Check browser console for errors
**Possible causes:**
* Invalid cube or measure names
* SQL syntax errors
* Missing dimensions or filters
* Data source connection issues
**Solutions:**
* Verify cube and measure names are correct
* Check SQL syntax
* Ensure required dimensions are included
* Verify data source connection
* Review error messages for specific issues
**Possible causes:**
* Large data volumes
* Inefficient queries
* Missing indexes
* Complex calculations
**Solutions:**
* Apply filters to reduce data volume
* Optimize query structure
* Check database indexes
* Simplify complex calculations
* Use pre-aggregations where possible
***
**Connect tools**
Learn how to use API credentials to connect BI tools and SQL clients.
**Manage projects**
Understand how to manage projects and branches for your cubes.