---
metadata:
  - name: generator
    content: Diplodoc Platform v5.62.0
alternate:
  - https://ydb.tech/docs/en/reference/sqs-api/examples.md?version=main
  - https://ydb.tech/docs/ru/reference/sqs-api/examples.md?version=main
  - href: https://ydb.tech/docs/en/reference/sqs-api/examples.md?version=main
    type: text/markdown
    title: Markdown version
  - href: https://ydb.tech/docs/en/llms.txt?revision=5f9509b7856960211eefd47b7217d87c71bdf904&version=main
    rel: describedby
sourcePath: en/core/reference/sqs-api/examples.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt?revision=5f9509b7856960211eefd47b7217d87c71bdf904&version=main

# Examples of working with a topic via the SQS API

<!-- markdownlint-disable blanks-around-fences -->

This article provides examples of working with [topics](https://ydb.tech/docs/en/concepts/datamodel/topic.md?version=main) using the SQS API with the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).

<!-- source: en/reference/sqs-api/_includes/examples_prerequisites.md -->
Before running the examples, configure access to the SQS API (in the Open Source version, disable the authentication requirement, see the section on [authentication](https://ydb.tech/docs/en/reference/sqs-api/auth.md?version=main)).

If you use AWS CLI, make sure it does not require configured AWS credentials: either add `--no-sign-request` to the commands, or set any values for `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`.
<!-- endsource: en/reference/sqs-api/_includes/examples_prerequisites.md -->

## Forming the endpoint for connection

The endpoint for accessing the SQS API is formed as follows:

`https://{db-balancer}:{port}/{database}`

Where:

- `db-balancer`: DNS name of the HTTPS load balancer with database compute nodes as its backend (or the address of the node or service where the HTTP Proxy is running).
- `port`: port on which the HTTP Proxy is available.
- `database`: full path of the database that contains the topics.

This endpoint is specified in the AWS CLI via the `--endpoint` parameter.

{% note info %}

The examples use the endpoint `https://my_db.balancer.example.com:8443/Root/my_db`. In it:

- `my_db.balancer.example.com`: DNS name of the load balancer through which the SQS protocol is available.
- `8443`: network port.
- `/Root/my_db`: database name.

{% endnote %}

## Creating a topic

To create a topic, run the command:


```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

aws --endpoint "$ENDPOINT" \
  sqs create-queue --queue-name "my_topic"
```


After running the command, a [topic](https://ydb.tech/docs/en/concepts/datamodel/topic.md?version=main) with the specified name and a [shared (common) reader](https://ydb.tech/docs/en/concepts/datamodel/topic.md?version=main#shared-consumer) named `ydb-sqs-consumer` will be created. You can check that the topic exists using the [scheme describe](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-describe.md?version=main) command of the [YDB CLI](https://ydb.tech/docs/en/reference/ydb-cli/index.md?version=main):


```shell
ydb -e grpcs://my_db.balancer.example.com:2135 -d /Root/my_db scheme describe my_topic
```


To create a FIFO queue, use the `FifoQueue=true` attribute. For FIFO queues, it is recommended to end the name with `.fifo` to comply with the Amazon SQS naming convention:


```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

aws --endpoint "$ENDPOINT" \
  sqs create-queue \
  --queue-name "my_topic.fifo" \
  --attributes FifoQueue=true
```


After running the command, a [topic](https://ydb.tech/docs/en/concepts/datamodel/topic.md?version=main) named `my_topic.fifo` and a [shared (common) reader](https://ydb.tech/docs/en/concepts/datamodel/topic.md?version=main#shared-consumer) named `ydb-sqs-consumer` will be created, with message ordering enabled.

## Getting a list of topics

To get a list of topics that can be accessed via the SQS protocol, run the command:


```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

aws --endpoint "$ENDPOINT" sqs list-queues
```


## Writing to and reading from a topic

For read and write operations, the AWS CLI uses the `--queue-url` parameter. You can obtain it via `get-queue-url`.

Below is an example:

- Getting `QueueUrl`.
- Writing a message.
- Reading a message.


```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

# get QueueUrl
QUEUE_URL="$(aws --endpoint "$ENDPOINT" sqs get-queue-url --queue-name "my_topic" --query 'QueueUrl' --output text)"

# write a message to the topic
aws --endpoint "$ENDPOINT" sqs send-message \
  --queue-url "$QUEUE_URL" \
  --message-body "hello from aws cli"

# read a message (long polling)
aws --endpoint "$ENDPOINT" sqs receive-message \
  --queue-url "$QUEUE_URL" \
  --wait-time-seconds 20 \
  --max-number-of-messages 1
```