Describe Command

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

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:

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:

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:

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:

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

Use Cases

1. Discover Available Queries

Find out what queries are available for exporting data:

graphman describe

2. Learn Query Structure

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

graphman describe --query policyByName

3. Find Queries by Pattern

Locate all queries related to a specific entity type:

graphman describe --query "service*"

4. Documentation Generation

Generate query documentation for reference:

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

5. Custom Query Development

Use as a reference when creating custom queries:

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: Use queries to export Gateway configuration
• import: Use mutations to import configuration
• schema: 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