# Create a query

Copy as Markdown[View as Markdown](/docs/development/guides/resources/messages/create-messages/create-query.md)

***

A query documents a request for information. Use queries when one part of your architecture asks another part to return data without changing state (e.g GET request)

![Example](/assets/images/example-48818df845c00beaebc32171dc270cf9.png)

## Adding a new query[​](#adding-a-new-query "Direct link to Adding a new query")

### Automatic Creation[​](#automatic-creation "Direct link to Automatic Creation")

Copy this prompt and paste it into your coding agent. Your agent can help you choose where the query should live, create the right folder structure, and add the first version of the query documentation.

### Manual Creation[​](#manual-creation "Direct link to Manual Creation")

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

* At the root of your catalog
* Inside a specific service folder

- queries
  <!-- -->
  /
  * GetOrder
    <!-- -->
    /
    * index.mdx
- services
  <!-- -->
  /
  * Orders
    <!-- -->
    /
    * queries
      <!-- -->
      /
      * GetOrder
        <!-- -->
        /
        * 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.

## Assign services to your queries[​](#assign-services-to-your-queries "Direct link to Assign services to your queries")

To add services that invoke or accept your query you can read the [guide on adding messages to services](/docs/development/guides/resources/messages/connect-messages/map-producers-and-consumers.md).

You can also assign your query to one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services.md) (e.g HTTP, GraphQL, etc).

**Added in** `eventcatalog@3.18.0`

## Document an HTTP operation[​](#document-an-http-operation "Direct link to Document an HTTP operation")

If your query maps to an HTTP endpoint, use the `operation` field to document the method, path, and expected status codes.

/queries/GetOrder/index.mdx (example)

```
---
id: GetOrder
# ...
operation:
  method: GET
  path: /orders/{id}
  statusCodes:
    - "200"
    - "404"
---
```

When defined, the visualiser shows an HTTP method badge, the API path, and colored status code pills on the query node. See the [messages reference](/docs/development/guides/resources/messages/reference.md#operation) for all available options.

## Adding schemas to your query[​](#adding-schemas-to-your-query "Direct link to Adding schemas to your query")

You can add any schema format to your query, you can read the [guide on adding schemas to messages](/docs/development/guides/resources/schemas/add-schemas-to-messages.md).