# Describe Command

## Overview

The `describe` command provides detailed information about available GraphQL queries and mutations, including their fields, arguments, and structure. It helps users understand what queries are available and how to use them.

## Syntax

```bash
graphman describe [--query <query-name>] [--output <output-file>]
```

## Parameters

### Optional Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--query` | Name of the query to describe (supports wildcards) | Lists all queries if omitted |
| `--output` | File to save the description output | Standard output (console) |

## Behavior

### Query Listing Mode

When no `--query` parameter is provided, the command lists all available queries organized by type:

- **Available Queries**: Standard GraphQL queries for retrieving data
- **Available Mutations**: GraphQL mutations for modifying data
- **Available In-built Queries**: Built-in GraphQL schema queries

### Query Description Mode

When a query name is provided:

- Displays the complete query structure including fields and arguments
- Supports wildcard patterns (e.g., `service*`, `*ByName`)
- Shows matching query names if multiple queries match the pattern

## Examples

### List All Available Queries

Display all queries, mutations, and built-in queries:

```bash
graphman describe
```

**Sample Output:**

```
available queries:
         all
         all:summary
         services
         serviceByName
         policies
         policyByName
         ...

available mutations:
         install-bundle
         delete-bundle
         ...

available in-built queries:
         __schema
         __type
         ...
```

### Describe a Specific Query

View the structure of a specific query:

```bash
graphman describe --query serviceByName
```

**Sample Output:**

```
query serviceByName
query serviceByName($name: String!) {
  serviceByName(name: $name) {
    name
    resolutionPath
    enabled
    policy {
      xml
    }
    ...
  }
}
```

### Describe with Wildcards

Find all queries matching a pattern:

```bash
graphman describe --query "*ByName"
```

**Sample Output:**

```
info: query *ByName
info: 5 matches found
         serviceByName
         policyByName
         folderByName
         encassConfigByName
         clusterPropertyByName
```

### Save Description to File

Export query description to a file:

```bash
graphman describe --query all --output all-query.gql
```

## Use Cases

### 1. Discover Available Queries

Find out what queries are available for exporting data:

```bash
graphman describe
```

### 2. Learn Query Structure

Understand the structure and required arguments for a query before using it:

```bash
graphman describe --query policyByName
```

### 3. Find Queries by Pattern

Locate all queries related to a specific entity type:

```bash
graphman describe --query "service*"
```

### 4. Documentation Generation

Generate query documentation for reference:

```bash
graphman describe --query all --output docs/all-query.gql
```

### 5. Custom Query Development

Use as a reference when creating custom queries:

```bash
graphman describe --query encass
```

## Query Types

### Standard Queries

Pre-defined queries for common operations:

- `all`: Export all Gateway entities
- `all:summary`: Export summary information for all entities
- `services`: Export all services
- `policies`: Export all policies
- `serviceByName`: Export a specific service by name
- `policyByName`: Export a specific policy by name

### Mutation Queries

Queries that modify Gateway configuration:

- `install-bundle`: Import and install a configuration bundle
- `delete-bundle`: Delete entities from the Gateway

### In-built Queries

GraphQL introspection queries:

- `__schema`: Query the GraphQL schema structure
- `__type`: Query information about specific types

## Important Notes

- Query names are case-sensitive
- Wildcard patterns use `*` to match any characters
- The describe command does not connect to a Gateway; it uses local query definitions
- Custom queries stored in the queries directory are also listed
- Mutations are distinguished from regular queries in the output

## Related Commands

- **[export](Export-Command.md)**: Use queries to export Gateway configuration
- **[import](Import-Command.md)**: Use mutations to import configuration
- **[schema](Schema-Command.md)**: View GraphQL schema information

## Advanced Usage

### Wildcard Patterns

| Pattern | Matches |
|---------|---------|
| `service*` | All queries starting with "service" |
| `*ByName` | All queries ending with "ByName" |
| `*policy*` | All queries containing "policy" |

### Custom Queries

Custom queries can be added to the queries directory and will appear in the describe output:

```
$GRAPHMAN_HOME/queries/<schema-version>/<query-name>.json
$GRAPHMAN_HOME/queries/<schema-version>/<query-name>.gql
```