<a id="flink-sql-describe"></a>

# DESCRIBE Statement in Confluent Cloud for Apache Flink

Confluent Cloud for Apache Flink® enables viewing the schema of an Apache Kafka® topic or
[materialized table](../../concepts/materialized-tables.md#flink-sql-materialized-tables). Also, you can
view details of an AI model, function, or connection.

## Syntax

```sql
-- View table details.
{ DESCRIBE | DESC } [EXTENDED] [catalog_name.][db_name.]table_name

-- View model details.
{ DESCRIBE | DESC } MODEL [[catalogname].[database_name]].model_name

-- View function details.
{ DESCRIBE | DESC } FUNCTION [EXTENDED] [catalog_name.][db_name.]function_name

-- View connection details.
{ DESCRIBE | DESC } CONNECTION [catalog_name.][db_name.]connection_name

-- View agent details.
{ DESCRIBE | DESC } AGENT [catalog_name.][db_name.]agent_name

-- View tool details.
{ DESCRIBE | DESC } TOOL [EXTENDED] [catalog_name.][db_name.]tool_name
```

## Description

The DESCRIBE statement shows the following properties of a table or
materialized table:

- Columns and their data type, including nullability constraints
- Primary keys
- Bucket keys, i.e., keys of distribution
- Implicit NOT NULL for primary key columns
- Custom [watermark](../../../_glossary.md#term-watermark)

The DESCRIBE EXTENDED statement shows all of the properties from the DESCRIBE
statement and also shows system columns, like `$rowtime`, including the
system watermark.

The DESCRIBE MODEL statement shows the following properties of an AI model:

- Input format
- Output format
- Model version
- isDefault version (yes or no)

The DESCRIBE FUNCTION statement shows the following properties of a function:

- System function (yes or no)
- Temporary (yes or no)
- Class name
- Function language
- Plugin ID
- Version ID
- Argument types
- Return type

The DESCRIBE FUNCTION EXTENDED statement shows all of the properties from the DESCRIBE FUNCTION
statement and also shows the following properties:

- Kind i.e. SCALAR, TABLE, or AGGREGATE
- Requirements e.g an aggregate function that can only be applied in an OVER window
- Deterministic (yes or no)
- Constant folding (yes or no)
- Signature

The DESCRIBE CONNECTION statement shows the following properties of a connection:

- Name
- Type
- Endpoint
- Comment

The DESCRIBE AGENT statement shows the following properties of an agent:

- Agent name
- Description
- Associated model
- Maximum iterations
- Tool configuration
- Input/output schema

The DESCRIBE TOOL statement shows the following properties of a tool:

- Tool name
- Tool type (function or connection)
- Associated resource (function or connection name)
- Description
- Tool options

## Examples

### Tables

In the Flink SQL shell or in a Cloud Console workspace, run the
following commands to see an example of the DESCRIBE statement.

1. Create a table.
   <!-- flink-sql-create-orders-table_start -->
   ```sql
   CREATE TABLE orders (
     `user` BIGINT NOT NULL,
     product STRING,
     amount INT,
     ts TIMESTAMP(3),
     PRIMARY KEY(`user`) NOT ENFORCED
   );
   ```

   Your output should resemble:
   ```none
   [INFO] Execute statement succeed.
   ```

   <!-- flink-sql-create-orders-table_end -->
2. View the table’s schema.
   ```sql
   DESCRIBE orders;
   ```

   Your output should resemble:
   ```none
   +-------------+--------------+----------+-------------------------+
   | Column Name |  Data Type   | Nullable |         Extras          |
   +-------------+--------------+----------+-------------------------+
   | user        | BIGINT       | NOT NULL | PRIMARY KEY, BUCKET KEY |
   | product     | STRING       | NULL     |                         |
   | amount      | INT          | NULL     |                         |
   | ts          | TIMESTAMP(3) | NULL     |                         |
   +-------------+--------------+----------+-------------------------+
   ```
3. View the table’s schema and system columns.
   ```sql
   DESCRIBE EXTENDED orders;
   ```

   Your output should resemble:
   ```none
   +-------------+----------------------------+----------+-----------------------------------------------------+---------+
   | Column Name |         Data Type          | Nullable |                       Extras                        | Comment |
   +-------------+----------------------------+----------+-----------------------------------------------------+---------+
   | user        | BIGINT                     | NOT NULL | PRIMARY KEY, BUCKET KEY                             |         |
   | product     | STRING                     | NULL     |                                                     |         |
   | amount      | INT                        | NULL     |                                                     |         |
   | ts          | TIMESTAMP(3)               | NULL     |                                                     |         |
   | $rowtime    | TIMESTAMP_LTZ(3) *ROWTIME* | NOT NULL | METADATA VIRTUAL, WATERMARK AS `SOURCE_WATERMARK`() | SYSTEM  |
   +-------------+----------------------------+----------+-----------------------------------------------------+---------+
   ```

<a id="flink-sql-describe-model"></a>

### Models

If you have an AI model registered in the Flink environment, you can view its
details and creation options by using the DESCRIBE MODEL statement.

The following code example shows how to view the default model version:

```sql
DESCRIBE MODEL `my-model`;
```

Your output should resemble:

```none
+-----------------------+---------------------------+---------------------------+---------+
|        Inputs         |          Outputs          |          Options          | Comment |
+-----------------------+---------------------------+---------------------------+---------+
| (                     | (                         | {                         |         |
|   `credit_limit` INT, |   `predicted_default` INT |   AZUREML.API_KEY=******, |         |
|   `age` INT           | )                         |   AZUREML.ENDPOINT=h...   |         |
| )                     |                           |                           |         |
+-----------------------+---------------------------+---------------------------+---------+
```

The following code example shows how to view a specific model version:

```sql
DESCRIBE MODEL `my-model$2`;
```

Your output should resemble:

```none
+-----------+------------------+-----------------------+---------------------------+--------------------+---------+
| VersionId | IsDefaultVersion |        Inputs         |          Outputs          |      Options       | Comment |
+-----------+------------------+-----------------------+---------------------------+--------------------+---------+
| 2         | true             | (                     | (                         | {                  |         |
|           |                  |   `credit_limit` INT, |   `predicted_default` INT |   AZUREML.API_K... |         |
|           |                  |   `age` INT           | )                         |                    |         |
|           |                  | )                     |                           |                    |         |
+-----------+------------------+-----------------------+---------------------------+--------------------+---------+
```

The following code example shows how to view all model versions:

```sql
DESCRIBE MODEL `my-model$all`;
```

Your output should resemble:

```none
+-----------+------------------+-----------------------+---------------------------+--------------------+---------+
| VersionId | IsDefaultVersion |        Inputs         |          Outputs          |      Options       | Comment |
+-----------+------------------+-----------------------+---------------------------+--------------------+---------+
| 1         | true             | (                     | (                         | {                  |         |
|           |                  |   `credit_limit` INT, |   `predicted_default` INT |   AZUREML.API_K... |         |
|           |                  |   `age` INT           | )                         |                    |         |
|           |                  | )                     |                           |                    |         |
| 2         | false            | (                     | (                         | {                  |         |
|           |                  |   `credit_limit` INT, |   `predicted_default` INT |   AZUREML.API_K... |         |
|           |                  |   `age` INT           | )                         |                    |         |
|           |                  | )                     |                           |                    |         |
+-----------+------------------+-----------------------+---------------------------+--------------------+---------+
```

For more information, see [Model versioning](create-model.md#flink-sql-create-model-input-model-versioning).

### Functions

You can view the details of any system functions or registered user-defined functions in the Flink environment,
by using the DESCRIBE FUNCTION statement.

The following code example shows how to describe a system function:

```sql
DESCRIBE FUNCTION `SUM`;
```

Your output should resemble:

```none
+-----------------+------------+
|       info name | info value |
+-----------------+------------+
| system function |       true |
|       temporary |      false |
+-----------------+------------+
```

View more details about the system function definition.

```sql
DESCRIBE FUNCTION EXTENDED `SUM`;
```

Your output should resemble:

```none
+------------------+----------------+
|        info name |     info value |
+------------------+----------------+
|  system function |           true |
|        temporary |          false |
|             kind |      AGGREGATE |
|     requirements |             [] |
|    deterministic |           true |
| constant folding |           true |
|        signature | SUM(<NUMERIC>) |
+------------------+----------------+
```

Here is what describing a user-defined function looks like

```sql
DESCRIBE FUNCTION `MyUpperCaseUdf`;
```

Your output should resemble:

```none
+-------------------+----------------------+
|         info name |           info value |
+-------------------+----------------------+
|   system function |                false |
|         temporary |                 true |
|        class name | org.example.UpperUDF |
| function language |                 JAVA |
|         plugin id |              ccp-xyz |
|        version id |              ver-123 |
|    argument types |                [str] |
|       return type |                  str |
+-------------------+----------------------+
```

View more details about the user-defined function definition.

```sql
DESCRIBE FUNCTION EXTENDED `MyUpperCaseUdf`;
```

Your output should resemble:

```none
+-------------------+-------------------------------+
|         info name |                    info value |
+-------------------+-------------------------------+
|   system function |                         false |
|         temporary |                          true |
|        class name |          org.example.UpperUDF |
| function language |                          JAVA |
|              kind |                        SCALAR |
|      requirements |                            [] |
|     deterministic |                          true |
|  constant folding |                          true |
|         signature | cat.db.MyUpperCaseUdf(STRING) |
|         plugin id |                       ccp-xyz |
|        version id |                       ver-123 |
|    argument types |                         [str] |
|       return type |                           str |
+-------------------+-------------------------------+
```

### Connections

You can view the details of any connection in the Flink environment
by using the DESCRIBE CONNECTION statement.

The following code example shows how to describe an example connection named
`azure-openai_connection`.

```sql
DESCRIBE CONNECTION `azure-openai_connection`;
```

Your output should resemble:

```none
+-------------------------+-------------+-----------------------------------------------------------------------+---------+
|          Name           |    Type     |                              Endpoint                                 | Comment |
+-------------------------+-------------+-----------------------------------------------------------------------+---------+
| azure-openai_connection | AZUREOPENAI | https://<your-project>.openai.azure.com/openai/deployments/matrix-... |         |
+-------------------------+-------------+-----------------------------------------------------------------------+---------+
```

### Agents

You can view the details of any agent in the Flink environment
by using the DESCRIBE AGENT statement.

The following code example shows how to describe an agent named
`claim_processor`.

```sql
DESCRIBE AGENT claim_processor;
```

Your output should resemble:

```none
+------------------+-------------------------------------------+-------------------+--------------------------+
|      model       |                  prompt                   |       tools       |        Comment           |
+------------------+-------------------------------------------+-------------------+--------------------------+
| tool_invoker     | Process claims using the appropriate tool |   process_claim   | Process insurance claims |
+------------------+-------------------------------------------+-------------------+--------------------------+
```

### Tools

You can view the details of any tool in the Flink environment
by using the DESCRIBE TOOL statement.

The following code example shows how to describe a tool named
`convert_to_celsius_tool`.

```sql
DESCRIBE TOOL convert_to_celsius_tool;
```

Your output should resemble:

```none
+---------------------------+-----------------------------------+------------------+
| Resource_identifier       |              options              | Comment          |
+---------------------------+-----------------------------------+------------------+
| `cat`.`db`.`myConnection` | {description=Test tool, type=mcp} | NULL             |
+---------------------------+-----------------------------------+------------------+
```

The following code example shows how to describe an MCP tool named
`mcp_server`.

```sql
DESCRIBE TOOL mcp_server;
```

Your output should resemble:

```none
+----------------------+-----------+------------------+--------------------------+
| tool_name            | tool_type | resource         | description              |
+----------------------+-----------+------------------+--------------------------+
| mcp_server           | connection| mcp_connection   | Weather API via MCP      |
+----------------------+-----------+------------------+--------------------------+
```

## Related content

- [CREATE AGENT](create-agent.md#flink-sql-create-agent)
- [CREATE CONNECTION](create-connection.md#flink-sql-create-connection)
- [CREATE FUNCTION](create-function.md#flink-sql-create-function)
- [CREATE MODEL](create-model.md#flink-sql-create-model)
- [CREATE MATERIALIZED TABLE](create-materialized-table.md#flink-sql-create-materialized-table)
- [CREATE TABLE](create-table.md#flink-sql-create-table)
- [CREATE TOOL](create-tool.md#flink-sql-create-tool)
- [USE CATALOG](use-catalog.md#flink-sql-use-catalog-statement)

#### NOTE
This website includes content developed at the [Apache Software Foundation](https://www.apache.org/)
under the terms of the [Apache License v2](https://www.apache.org/licenses/LICENSE-2.0.html).