Skip to main content

Creating queries

Queries live in a /queries folder. This folder can be placed:

  • At the root of your catalog, or
    • /queries/{Query Name}/index.mdx
  • Inside a specific service folder.
    • /services/{Service Name}/queries/{Query Name}/index.mdx

The contents are split into two sections, frontmatter and the markdown content.

Here is an example of what a query markdown file may look like.

/queries/GetOrder/index.mdx (example)
---
# id of your query, used for slugs and references in EventCatalog.
id: GetOrder

# Display name of the query, rendered in EventCatalog
name: Get Order

# Version of the query
version: 0.0.4

# Short summary of your query
summary: |
    Query with the intent to get an order from the system

# Optional owners, references teams or users
owners:
    - dboyne

# Optional badges, rendered to UI by EventCatalog
badges:
    - content: New service
      backgroundColor: blue
      textColor: blue
---

## Overview

The `GetOrder` query represents intent to get an order from the system.

<NodeGraph />

Once this file is added, the query will automatically appear across EventCatalog.

Writing query content​

You can write any Markdown inside a query.

Each query gets its own page, so use this space to fully explain how it works.

You can also use interactive components to enrich your documentation.

Assign services to your queries​

To add services that invoke or accept your query you can read the guide on adding messages to services.

You can also assign your query to one or more channels (e.g HTTP, GraphQL, etc).

Adding schemas to your query​

You can add any schema format to your query, you can read the guide on adding schemas to messages.

What should I document?​

There’s no strict structure, but consider including:

  • Purpose – What does this query do and why does it exist?
  • How to trigger it – APIs, SDKs, or UI actions
  • Schema – Payload structure and validation rules
  • Ownership – Who maintains this query?
  • Contributing – How others can propose changes

How do queries appear in EventCatalog?​

Example