Metadata Endpoints
The metadata endpoints allow you to discover and explore the cubes, metrics, and dimensions available in your Olytix Core semantic layer.
GET /api/v1/query/meta/cubes
List all available cubes in the semantic layer.
Request
curl -X GET "http://localhost:8000/api/v1/query/meta/cubes" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"cubes": [
{
"name": "orders",
"title": "Orders",
"description": "Order transactions and revenue metrics",
"measures": [
{
"name": "count",
"cube": "orders",
"type": "count",
"title": "Order Count",
"description": "Total number of orders",
"format": null,
"drill_members": ["order_id", "order_date", "customer_id"]
},
{
"name": "total_revenue",
"cube": "orders",
"type": "sum",
"title": "Total Revenue",
"description": "Sum of all order amounts",
"format": "currency",
"drill_members": ["order_id", "order_date", "amount"]
},
{
"name": "average_order_value",
"cube": "orders",
"type": "avg",
"title": "Average Order Value",
"description": "Average amount per order",
"format": "currency",
"drill_members": []
}
],
"dimensions": [
{
"name": "order_id",
"cube": "orders",
"type": "number",
"title": "Order ID",
"description": "Unique order identifier",
"primary_key": true,
"granularities": []
},
{
"name": "order_date",
"cube": "orders",
"type": "time",
"title": "Order Date",
"description": "Date when the order was placed",
"primary_key": false,
"granularities": ["day", "week", "month", "quarter", "year"]
},
{
"name": "status",
"cube": "orders",
"type": "string",
"title": "Order Status",
"description": "Current order status",
"primary_key": false,
"granularities": []
},
{
"name": "region",
"cube": "orders",
"type": "string",
"title": "Region",
"description": "Geographic region",
"primary_key": false,
"granularities": []
}
],
"segments": ["completed_orders", "high_value_orders"],
"joins": ["customers", "products"]
},
{
"name": "customers",
"title": "Customers",
"description": "Customer information and lifetime metrics",
"measures": [
{
"name": "count",
"cube": "customers",
"type": "count",
"title": "Customer Count",
"description": "Total number of customers",
"format": null,
"drill_members": ["customer_id", "name", "email"]
},
{
"name": "lifetime_value",
"cube": "customers",
"type": "sum",
"title": "Customer Lifetime Value",
"description": "Total revenue from customer",
"format": "currency",
"drill_members": []
}
],
"dimensions": [
{
"name": "customer_id",
"cube": "customers",
"type": "number",
"title": "Customer ID",
"description": "Unique customer identifier",
"primary_key": true,
"granularities": []
},
{
"name": "name",
"cube": "customers",
"type": "string",
"title": "Customer Name",
"description": "Full customer name",
"primary_key": false,
"granularities": []
},
{
"name": "signup_date",
"cube": "customers",
"type": "time",
"title": "Signup Date",
"description": "Date when customer signed up",
"primary_key": false,
"granularities": ["day", "week", "month", "year"]
}
],
"segments": ["active_customers", "churned_customers"],
"joins": ["orders"]
}
]
}
GET /api/v1/query/meta/cubes/{cube_name}
Get detailed information about a specific cube.
Request
curl -X GET "http://localhost:8000/api/v1/query/meta/cubes/orders" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"name": "orders",
"title": "Orders",
"description": "Order transactions and revenue metrics",
"measures": [
{
"name": "count",
"cube": "orders",
"type": "count",
"title": "Order Count",
"description": "Total number of orders",
"format": null,
"drill_members": ["order_id", "order_date", "customer_id"]
},
{
"name": "total_revenue",
"cube": "orders",
"type": "sum",
"title": "Total Revenue",
"description": "Sum of all order amounts",
"format": "currency",
"drill_members": ["order_id", "order_date", "amount"]
}
],
"dimensions": [
{
"name": "order_id",
"cube": "orders",
"type": "number",
"title": "Order ID",
"description": "Unique order identifier",
"primary_key": true,
"granularities": []
},
{
"name": "order_date",
"cube": "orders",
"type": "time",
"title": "Order Date",
"description": "Date when the order was placed",
"primary_key": false,
"granularities": ["day", "week", "month", "quarter", "year"]
}
],
"segments": ["completed_orders", "high_value_orders"],
"joins": ["customers", "products"]
}
GET /api/v1/query/meta/metrics
List all available metrics (measures) across all cubes.
Request
curl -X GET "http://localhost:8000/api/v1/query/meta/metrics" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"measures": [
{
"name": "count",
"cube": "orders",
"type": "count",
"title": "Order Count",
"description": "Total number of orders",
"format": null,
"drill_members": ["order_id", "order_date", "customer_id"]
},
{
"name": "total_revenue",
"cube": "orders",
"type": "sum",
"title": "Total Revenue",
"description": "Sum of all order amounts",
"format": "currency",
"drill_members": ["order_id", "order_date", "amount"]
},
{
"name": "average_order_value",
"cube": "orders",
"type": "avg",
"title": "Average Order Value",
"description": "Average amount per order",
"format": "currency",
"drill_members": []
},
{
"name": "count",
"cube": "customers",
"type": "count",
"title": "Customer Count",
"description": "Total number of customers",
"format": null,
"drill_members": ["customer_id", "name", "email"]
},
{
"name": "lifetime_value",
"cube": "customers",
"type": "sum",
"title": "Customer Lifetime Value",
"description": "Total revenue from customer",
"format": "currency",
"drill_members": []
}
]
}
Measure Types
| Type | Description |
|---|---|
count | Count of rows |
count_distinct | Count of distinct values |
sum | Sum of values |
avg | Average of values |
min | Minimum value |
max | Maximum value |
number | Custom numeric calculation |
running_total | Cumulative sum |
GET /api/v1/query/meta/dimensions
List all available dimensions across all cubes.
Request
curl -X GET "http://localhost:8000/api/v1/query/meta/dimensions" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"dimensions": [
{
"name": "order_id",
"cube": "orders",
"type": "number",
"title": "Order ID",
"description": "Unique order identifier",
"primary_key": true,
"granularities": []
},
{
"name": "order_date",
"cube": "orders",
"type": "time",
"title": "Order Date",
"description": "Date when the order was placed",
"primary_key": false,
"granularities": ["day", "week", "month", "quarter", "year"]
},
{
"name": "status",
"cube": "orders",
"type": "string",
"title": "Order Status",
"description": "Current order status",
"primary_key": false,
"granularities": []
},
{
"name": "region",
"cube": "orders",
"type": "string",
"title": "Region",
"description": "Geographic region",
"primary_key": false,
"granularities": []
},
{
"name": "customer_id",
"cube": "customers",
"type": "number",
"title": "Customer ID",
"description": "Unique customer identifier",
"primary_key": true,
"granularities": []
},
{
"name": "signup_date",
"cube": "customers",
"type": "time",
"title": "Signup Date",
"description": "Date when customer signed up",
"primary_key": false,
"granularities": ["day", "week", "month", "year"]
}
]
}
Dimension Types
| Type | Description |
|---|---|
string | Text/categorical values |
number | Numeric values |
time | Date/time values with granularity support |
boolean | True/false values |
geo | Geographic data (latitude/longitude) |
Time Granularities
Time dimensions support these granularities:
| Granularity | Description | Example |
|---|---|---|
second | By second | 2024-01-15 10:30:45 |
minute | By minute | 2024-01-15 10:30 |
hour | By hour | 2024-01-15 10:00 |
day | By day | 2024-01-15 |
week | By week | 2024-W03 |
month | By month | 2024-01 |
quarter | By quarter | 2024-Q1 |
year | By year | 2024 |
POST /api/v1/query/meta/cubes
Register a new cube in the semantic layer.
Request
curl -X POST http://localhost:8000/api/v1/query/meta/cubes \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "products",
"sql_table": "public.products",
"title": "Products",
"description": "Product catalog and inventory",
"measures": [
{
"name": "count",
"type": "count",
"title": "Product Count"
},
{
"name": "total_inventory",
"type": "sum",
"sql": "inventory_quantity",
"title": "Total Inventory"
}
],
"dimensions": [
{
"name": "product_id",
"type": "number",
"sql": "id",
"title": "Product ID",
"primary_key": true
},
{
"name": "name",
"type": "string",
"sql": "product_name",
"title": "Product Name"
},
{
"name": "category",
"type": "string",
"sql": "category",
"title": "Category"
},
{
"name": "created_at",
"type": "time",
"sql": "created_at",
"title": "Created At",
"granularities": ["day", "month", "year"]
}
]
}'
Response (201 Created)
{
"name": "products",
"title": "Products",
"description": "Product catalog and inventory",
"measures": [
{
"name": "count",
"cube": "products",
"type": "count",
"title": "Product Count",
"description": null,
"format": null,
"drill_members": []
},
{
"name": "total_inventory",
"cube": "products",
"type": "sum",
"title": "Total Inventory",
"description": null,
"format": null,
"drill_members": []
}
],
"dimensions": [
{
"name": "product_id",
"cube": "products",
"type": "number",
"title": "Product ID",
"description": null,
"primary_key": true,
"granularities": []
},
{
"name": "name",
"cube": "products",
"type": "string",
"title": "Product Name",
"description": null,
"primary_key": false,
"granularities": []
}
],
"segments": [],
"joins": []
}
DELETE /api/v1/query/meta/cubes/{cube_name}
Delete a cube from the semantic layer.
Request
curl -X DELETE "http://localhost:8000/api/v1/query/meta/cubes/products" \
-H "Authorization: Bearer YOUR_API_KEY"
Response (204 No Content)
No response body on successful deletion.
Error Responses
400 Bad Request - Cube Already Exists
{
"detail": "Cube products already exists"
}
404 Not Found
{
"detail": "Cube invalid_cube not found"
}
Using Metadata in Queries
Once you have discovered the available cubes, metrics, and dimensions, you can use them in queries.
Example: Query Using Discovered Metadata
# First, discover what's available
curl -X GET "http://localhost:8000/api/v1/query/meta/cubes/orders" \
-H "Authorization: Bearer YOUR_API_KEY"
# Then construct a query using the discovered measures and dimensions
curl -X POST http://localhost:8000/api/v1/query \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"measures": ["orders.total_revenue", "orders.count"],
"dimensions": ["orders.region", "orders.order_date"],
"time_dimensions": [
{
"dimension": "orders.order_date",
"granularity": "month",
"date_range": ["2024-01-01", "2024-12-31"]
}
],
"limit": 100
}'