Logical Table
Learn about Logical Tables in Apache Pinot, which provide a unified query interface over multiple physical tables for flexible data organization.
A logical table in Pinot provides a unified query interface over multiple physical tables. Instead of querying individual tables separately, users can query a single logical table that transparently routes the query to all underlying physical tables and aggregates the results.
Overview
Logical tables are useful for:
Geographic/Regional partitioning: Split data by region (e.g.,
ordersUS,ordersEU,ordersAPAC) while providing a unifiedorderstable for queriesTable partitioning strategies: Organize data across multiple physical tables based on business logic
Time-based table splitting: Combine historical and recent data from different physical tables
How It Works
When you query a logical table, Pinot:
Resolves the logical table name to its list of physical tables
Routes the query to all relevant physical tables (both offline and realtime)
Aggregates results from all physical tables
Returns a unified result set to the client
For hybrid logical tables (containing both offline and realtime physical tables), Pinot uses a configurable time boundary strategy to determine which segments to query from each table type, avoiding duplicate data.
Logical Table Configuration
A logical table configuration defines the mapping between the logical table and its physical tables.
Configuration Properties
tableName
Name of the logical table
Yes
brokerTenant
The broker tenant to use for routing
Yes
physicalTableConfigMap
Map of physical table names to their configurations
Yes
refOfflineTableName
Reference offline table for table config metadata
Required if offline tables exist
refRealtimeTableName
Reference realtime table for table config metadata
Required if realtime tables exist
query
Query configuration (timeout, response size limits, etc.)
No
quota
Quota configuration for rate limiting
No
timeBoundaryConfig
Time boundary configuration for hybrid tables
Required for hybrid logical tables
Example Configuration
Hybrid Logical Table Configuration
For logical tables that combine both offline and realtime physical tables:
Creating a Logical Table
Step 1: Create the Schema
Create a schema that matches the structure of your physical tables:
Upload the schema:
Step 2: Create the Logical Table
Managing Logical Tables
List Logical Tables
Get Logical Table Configuration
Update Logical Table
Delete Logical Table
Querying Logical Tables
Query a logical table just like any other Pinot table:
Logical tables work with both the single-stage and multi-stage query engines.
Time Boundary Configuration
For hybrid logical tables that contain both offline and realtime physical tables, you must configure a time boundary strategy to avoid querying duplicate data.
Available Strategies
min
Uses the minimum time boundary from the specified tables
Configuration Example
The includedTables parameter specifies which physical tables should be considered when computing the time boundary.
Query Configuration
Logical tables support query-level configurations:
timeoutMs
Query timeout in milliseconds
disableGroovy
Disable Groovy functions in queries
maxServerResponseSizeBytes
Maximum response size from each server
maxQueryResponseSizeBytes
Maximum total query response size
Quota Configuration
Apply rate limiting to logical tables:
Quick Start Example
Try the logical table quickstart to see the feature in action:
This quickstart:
Creates three physical tables:
ordersUS_OFFLINE,ordersEU_OFFLINE, andordersAPAC_OFFLINECreates a logical table
ordersthat unifies all threeDemonstrates queries on both physical and logical tables
Validation Rules
When creating or updating a logical table, Pinot validates:
Table name does not end with
_OFFLINEor_REALTIMEAll physical tables exist (unless marked as
multiCluster)Physical tables are in the same database as the logical table
Schema with the same name as the logical table exists
Broker tenant exists
Reference table names (
refOfflineTableName,refRealtimeTableName) are set correctlyTime boundary config is provided for hybrid tables
Limitations
All physical tables must have compatible schemas
Storage quota is not supported
Physical tables in the same logical table should ideally have consistent indexing for optimal query performance
See Also
Last updated
Was this helpful?

