# Controller Admin API

## Controller Admin API

The controller admin UI at `http://<controller-host>:<port>/help` is the quickest way to inspect and exercise Pinot's administrative endpoints. Use it for schema, table, and segment operations when you want the interactive Swagger surface instead of raw curl examples.

### What It Covers

| Area     | Typical task                                    |
| -------- | ----------------------------------------------- |
| Tables   | List, inspect, delete, and update table configs |
| Schemas  | List, inspect, create, and delete schemas       |
| Segments | List, inspect, upload, and reload segments      |

### Operational Reminder

Controller APIs are for administrative tasks. Use the broker query API for querying Pinot, even if the controller UI also exposes a query console.

### What this page covered

* The controller Swagger UI entry point.
* Which administrative tasks belong in the controller UI.
* Why the broker query API still owns SQL execution.

### Next step

Use the Swagger UI to confirm the endpoint shape, then jump to the controller API examples page when you need exact curl payloads.

### Related pages

* [API Reference](https://docs.pinot.apache.org/reference/api-reference)
* [Controller API Examples](https://docs.pinot.apache.org/reference/api-reference/controller-api)
* [Broker Query API](https://docs.pinot.apache.org/reference/api-reference/query-api)
* [Query Response Format](https://docs.pinot.apache.org/reference/api-reference/query-response-format)

## Controller Admin API

The [Pinot Admin UI](http://localhost:9000/help) contains all the APIs that you will need to operate and manage your cluster. It provides a set of APIs for Pinot cluster management including health check, instances management, schema and table management, data segments management.

Note: The controller API's are primarily for admin tasks. Even though the UI console queries Pinot when running queries from the query console, use the [Broker Query API](https://docs.pinot.apache.org/readme) for querying Pinot.

![](https://459170765-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LtH6nl58DdnZnelPdTc%2F-M1BuoMXn83szIeNCWPT%2F-M1BxN51vPW0p9FFuJCK%2FScreen%20Shot%202020-02-28%20at%2010.00.43%20AM.png?alt=media\&token=283f9390-5d08-4d62-a39f-7746a8cd638c)

Let's check out the tables in this cluster by going to [Table -> List all tables in cluster](http://localhost:9000/help#!/Table/listTableConfigs) and click on `Try it out!`. We can see the `baseballStats` table listed here. We can also see the exact `curl` call made to the controller API.

![List all tables in cluster](https://459170765-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtH6nl58DdnZnelPdTc-887967055%2Fuploads%2FjZvHBNiaj3QxqUfLGKbx%2Fimage.png?alt=media\&token=91e8c047-83b0-4cbc-ad2c-7faf83ef92e1)

You can look at the configuration of this table by going to [Tables -> Get/Enable/Disable/Drop a table](http://localhost:9000/help#!/Table/alterTableStateOrListTableConfig), type in `baseballStats` in the table name, and click `Try it out!`

Let's check out the schemas in the cluster by going to [Schema -> List all schemas in the cluster](http://localhost:9000/help#!/Schema/listSchemaNames) and click `Try it out!`. We can see a schema called `baseballStats` in this list.

![List all schemas in the cluster](https://459170765-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtH6nl58DdnZnelPdTc-887967055%2Fuploads%2Fs2RDC0IqDvJuMgade8qD%2Fimage.png?alt=media\&token=9164297b-41c4-438e-b507-9d73948f4bca)

Take a look at the schema by going to [Schema -> Get a schema](http://localhost:9000/help#!/Schema/getSchema), type `baseballStats` in the schema name, and click `Try it out!`.

```
{
  "schemaName": "baseballStats",
  "dimensionFieldSpecs": [
    {
      "name": "playerID",
      "dataType": "STRING"
    },
    {
      "name": "yearID",
      "dataType": "INT"
    },
    {
      "name": "teamID",
      "dataType": "STRING"
    },
    {
      "name": "league",
      "dataType": "STRING"
    },
    {
      "name": "playerName",
      "dataType": "STRING"
    }
  ],
  "metricFieldSpecs": [
    {
      "name": "playerStint",
      "dataType": "INT"
    },
    {
      "name": "numberOfGames",
      "dataType": "INT"
    },
    {
      "name": "numberOfGamesAsBatter",
      "dataType": "INT"
    },
    {
      "name": "AtBatting",
      "dataType": "INT"
    },
    {
      "name": "runs",
      "dataType": "INT"
    },
    {
      "name": "hits",
      "dataType": "INT"
    },
    {
      "name": "doules",
      "dataType": "INT"
    },
    {
      "name": "tripples",
      "dataType": "INT"
    },
    {
      "name": "homeRuns",
      "dataType": "INT"
    },
    {
      "name": "runsBattedIn",
      "dataType": "INT"
    },
    {
      "name": "stolenBases",
      "dataType": "INT"
    },
    {
      "name": "caughtStealing",
      "dataType": "INT"
    },
    {
      "name": "baseOnBalls",
      "dataType": "INT"
    },
    {
      "name": "strikeouts",
      "dataType": "INT"
    },
    {
      "name": "intentionalWalks",
      "dataType": "INT"
    },
    {
      "name": "hitsByPitch",
      "dataType": "INT"
    },
    {
      "name": "sacrificeHits",
      "dataType": "INT"
    },
    {
      "name": "sacrificeFlies",
      "dataType": "INT"
    },
    {
      "name": "groundedIntoDoublePlays",
      "dataType": "INT"
    },
    {
      "name": "G_old",
      "dataType": "INT"
    }
  ]
}
```

Finally, let's checkout the data segments in the cluster by going to [List all segments](http://localhost:9000/help#!/Segment/getSegments), type in `baseballStats` in the table name, and click `Try it out!`. There's 1 segment for this table, called `baseballStats_OFFLINE_0`.

### Deleting tables and schemas

You can delete tables and schemas using the REST API or the Pinot Data Explorer UI.

#### Using the API

To delete a table, send a `DELETE` request to `/tables/{tableName}`. By default, segments are moved to a deleted-segments area and retained for a period (default 7 days) before permanent removal. To delete segments immediately with no retention, pass `retention=0d`:

```
curl -X DELETE "http://localhost:9000/tables/baseballStats?retention=0d" -H "accept: application/json"
```

To also delete the schema after deleting the table, send a separate `DELETE` request:

```
curl -X DELETE "http://localhost:9000/schemas/baseballStats" -H "accept: application/json"
```

{% hint style="warning" %}
Using `retention=0d` permanently deletes all data immediately with no possibility of recovery. Only use this for development, testing, or cleanup scenarios where the data is no longer needed.
{% endhint %}

For more details on the delete table API and its parameters, see the [Controller API Examples](https://docs.pinot.apache.org/reference/controller-api#delete-tablestablename).

#### Using the Data Explorer UI

In the Pinot Data Explorer, navigate to a table and click **Delete Table**. The delete dialog provides two options:

* **Delete Immediately** -- Bypasses the default segment retention period and deletes all segments right away. This is equivalent to passing `retention=0d` in the API. This is useful for large tables where the default delete operation might time out.
* **Delete Schema** -- After successfully deleting the table, also deletes the associated schema. This only works if no other tables are using the same schema.

You might have figured out by now, in order to get data into the Pinot cluster, we need a table, a schema, and segments. Continue with [First table and schema](https://docs.pinot.apache.org/start-here/first-table-and-schema) and then [First batch ingest](https://docs.pinot.apache.org/start-here/first-batch-ingest) to create them for your own data.