> For the complete documentation index, see [llms.txt](https://docs.pinot.apache.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pinot.apache.org/build-with-pinot/data-modeling/schema.md).

# Schema and Table Shape

A Pinot schema defines the columns that exist in a table and how Pinot should treat them. The important part is not only the column list, but also the shape of the table: which fields are dimensions, metrics, and time fields, how nulls behave, and whether the table is built for offline, realtime, or hybrid ingestion.

Pinot stores schema and table metadata separately, but the two should be designed together. Keep the schema narrow enough to match the data you actually query, and keep the table config dense enough for reference pages rather than this narrative overview.

## What to design

The schema answers four practical questions:

* What columns exist?
* What data type does each column use?
* Which columns are dimensions, metrics, or date-time fields?
* How should Pinot handle missing values and time semantics?

## Good defaults

Use column names that are stable and business-facing. Prefer simple types that match the source data. Add only the fields you need at query time, because schema changes are additive and should be deliberate.

For time columns, keep one primary time field in mind for retention and hybrid-table boundary behavior. For null handling, decide early whether the table needs column-based or table-based semantics.

For new schemas, model time columns with `dateTimeFieldSpecs` only. Pinot's REST schema submission paths now reject the deprecated `TimeFieldSpec` (`fieldType=TIME`) and require `DateTimeFieldSpec` instead. Legacy schemas that are already stored in the cluster can still load internally for backward compatibility.

## Example schema

```json
{
  "schemaName": "orders",
  "enableColumnBasedNullHandling": true,
  "dimensionFieldSpecs": [
    { "name": "orderId", "dataType": "STRING" },
    { "name": "customerId", "dataType": "STRING" },
    { "name": "region", "dataType": "STRING" }
  ],
  "metricFieldSpecs": [
    { "name": "amount", "dataType": "DOUBLE", "defaultNullValue": 0 }
  ],
  "dateTimeFieldSpecs": [
    {
      "name": "eventTime",
      "dataType": "LONG",
      "format": "EPOCH",
      "granularity": "1:DAYS"
    }
  ]
}
```

## When to use the reference pages

Use the [schema reference](/reference/configuration-reference/schema.md) when you need the exact JSON fields, validation rules, or date-time field formats. Use the [table reference](/reference/configuration-reference/table.md) when you need indexing, retention, or routing configuration.

## What this page covered

This page covered the parts of Pinot schema design that shape ingestion and query behavior.

## Next step

Read [Logical Tables](/build-with-pinot/data-modeling/logical-tables.md) if one query name should route to multiple physical tables.

## Related pages

* [Data Modeling](/build-with-pinot/data-modeling.md)
* [Logical Tables](/build-with-pinot/data-modeling/logical-tables.md)
* [Schema Evolution](/build-with-pinot/data-modeling/schema-evolution.md)
* [Schema Reference](/reference/configuration-reference/schema.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pinot.apache.org/build-with-pinot/data-modeling/schema.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.