Skip to main content

Creating queries

Added in eventcatalog@2.10.0

Adding an query to your EventCatalog is a great way for you to document your messages.

What do queries look like in EventCatalog?​

Example

Adding a new query​

To add a new query create a new folder within the /queries folder with an index.md file.

  • /queries/{Query Name}/index.md
    • (example /queries/GetOrder/index.md)

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

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

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

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

# Version of the query
version: 0.0.1

# Short summary of your query
summary: |
  GET request (query) that requests the latest information for a given order.

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

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

## Overview

The `GetOrder` message is a query used to retrieve detailed information about a specific order, identified by its `orderId`. It provides information such as the order status (e.g., pending, completed, shipped), the items within the order, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.

This query can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time order data for tracking, auditing, or managing customer purchases.

<NodeGraph />

That's it!

Once you add your new query to EventCatalog, it will now show in the docs, visualizer and discoverability table.

Adding content​

With queries you can write any Markdown you want and it will render on your page. Every query gets its own page.

Within your markdown content you can use components to add interactive components to your page.

Tips for query content​

It's entirely up to you what you want to add to your queries markdown content but here are a few things you might want to consider.

  • Context of the query. What is it? Why does it exist?
  • How can others trigger this query?
  • What is the schema of the query?
  • How can others make contributions to changes to this query? Who do they contact (owners?)
  • Any edit/contributing guidelines?