# SQL syntax

Pinot uses the Apache Calcite SQL parser with the `MYSQL_ANSI` dialect. This page is the practical overview: it explains the syntax patterns most people use every day and points to the deeper reference when you need the full operator list.

## Core rules

* Use single quotes for string literals.
* Use double quotes for identifiers when a column name is reserved or contains special characters.
* `SET` statements apply query options before the query runs.
* `EXPLAIN PLAN FOR` shows how Pinot will execute a query without returning data.

```sql
SET useMultistageEngine = true;
SELECT "date", city, COUNT(*)
FROM orders
WHERE status = 'shipped'
GROUP BY "date", city
ORDER BY "date" DESC
LIMIT 20;
```

## Common query shapes

Pinot supports the usual `SELECT`, `WHERE`, `GROUP BY`, `ORDER BY`, and `LIMIT` patterns.

Typical query shapes include:

* filtering a table and returning a small result set
* grouping and aggregating by one or more dimensions
* using `ORDER BY` to rank rows before a `LIMIT`
* using `CASE WHEN` and scalar functions in select lists

## Engine-aware syntax

Some SQL features depend on the engine:

* single-stage execution is best for simple analytic queries
* multi-stage execution is required for joins, subqueries, and several advanced distributed patterns
* `EXPLAIN PLAN FOR` is the best way to see how Pinot interprets a statement

If you are working on a query and do not know whether a feature is supported, check the engine-specific guidance before you assume the syntax is invalid.

## Table DDL runs on the controller

Pinot also supports SQL table DDL, but it is exposed through the controller rather than the broker query path. Use `POST /sql/ddl` for `CREATE TABLE`, `DROP TABLE`, `SHOW TABLES`, and `SHOW CREATE TABLE`.

This distinction matters because the SSE and MSE engines still execute query statements, not controller metadata changes. If you want the syntax and examples for controller-managed DDL, use [SQL Table DDL](/build-with-pinot/querying-and-sql/sql-syntax/sql-ddl.md).

## Where the details live

This page intentionally stays light. For the full statement-by-statement reference, use the detailed [SQL syntax and operators reference](/build-with-pinot/querying-and-sql/sql-syntax/sql-reference.md). For controller-managed table DDL, use [SQL Table DDL](/build-with-pinot/querying-and-sql/sql-syntax/sql-ddl.md). For query controls and diagnostics, use the pages under `query-execution-controls/`.

## What this page covered

This page covered the main Pinot SQL rules, the most common statement patterns, and the difference between narrative guidance and the full SQL reference.

## Next step

Read [Querying Pinot](/build-with-pinot/querying-and-sql/querying-pinot.md) for the broader query workflow, or jump to [Query options](/build-with-pinot/querying-and-sql/query-execution-controls/query-options.md) if you want to control runtime behavior.

## Related pages

* [Querying Pinot](/build-with-pinot/querying-and-sql/querying-pinot.md)
* [SQL Table DDL](/build-with-pinot/querying-and-sql/sql-syntax/sql-ddl.md)
* [Query options](/build-with-pinot/querying-and-sql/query-execution-controls/query-options.md)
* [Explain plan](/build-with-pinot/querying-and-sql/query-execution-controls/explain-plan.md)


---

# Agent Instructions: 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:

```
GET https://docs.pinot.apache.org/build-with-pinot/querying-and-sql/sql-syntax.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.