# RPC (/sdks/elixir/reference/rpc)



<Callout type="info" title="Which to use">
  This page is the field-level struct reference for `Command`/`Query`/`CommandReply`/`QueryReply`. For the task-oriented walkthroughs of handling incoming requests, see [Handle Command](/sdks/elixir/how-to/rpc/command-handle) and [Handle Query](/sdks/elixir/how-to/rpc/query-handle).
</Callout>

RPC (Remote Procedure Call) provides synchronous request/response messaging through Commands (fire-and-wait, no data return) and Queries (request data with optional server-side caching).

## Command Structs [#command-structs]

### KubeMQ.Command [#kubemqcommand]

Sent by the caller.

| Field       | Type                     | Description                      |
| ----------- | ------------------------ | -------------------------------- |
| `id`        | `String.t()`             | Auto-generated request ID        |
| `channel`   | `String.t()`             | Target channel                   |
| `metadata`  | `String.t()`             | Optional metadata                |
| `body`      | `String.t() \| binary()` | Request payload                  |
| `timeout`   | `pos_integer()`          | Response timeout in milliseconds |
| `client_id` | `String.t()`             | Sender client ID                 |
| `tags`      | `map()`                  | Optional key-value tags          |

### KubeMQ.CommandReceive [#kubemqcommandreceive]

Received by the handler.

| Field           | Type                     | Description                   |
| --------------- | ------------------------ | ----------------------------- |
| `id`            | `String.t()`             | Request ID                    |
| `channel`       | `String.t()`             | Source channel                |
| `metadata`      | `String.t()`             | Metadata                      |
| `body`          | `String.t() \| binary()` | Request payload               |
| `reply_channel` | `String.t()`             | Channel for sending the reply |
| `tags`          | `map()`                  | Key-value tags                |

### KubeMQ.CommandReply [#kubemqcommandreply]

Returned by the handler callback.

| Field         | Type         | Description                     |
| ------------- | ------------ | ------------------------------- |
| `request_id`  | `String.t()` | Matches the received command ID |
| `response_to` | `String.t()` | Matches the reply channel       |
| `executed`    | `boolean()`  | Whether the command succeeded   |
| `error`       | `String.t()` | Error message if failed         |
| `metadata`    | `String.t()` | Optional response metadata      |

### KubeMQ.CommandResponse [#kubemqcommandresponse]

Returned to the caller from `send_command/2`.

| Field         | Type         | Description         |
| ------------- | ------------ | ------------------- |
| `command_id`  | `String.t()` | Command ID          |
| `executed`    | `boolean()`  | Success flag        |
| `executed_at` | `integer()`  | Execution timestamp |
| `error`       | `String.t()` | Error if failed     |

## Query Structs [#query-structs]

### KubeMQ.Query [#kubemqquery]

Sent by the caller. Supports server-side caching.

| Field       | Type                     | Description                       |
| ----------- | ------------------------ | --------------------------------- |
| `id`        | `String.t()`             | Auto-generated request ID         |
| `channel`   | `String.t()`             | Target channel                    |
| `metadata`  | `String.t()`             | Optional metadata                 |
| `body`      | `String.t() \| binary()` | Request payload                   |
| `timeout`   | `pos_integer()`          | Response timeout in milliseconds  |
| `cache_key` | `String.t()`             | Cache key for server-side caching |
| `cache_ttl` | `pos_integer()`          | Cache TTL in milliseconds         |
| `client_id` | `String.t()`             | Sender client ID                  |
| `tags`      | `map()`                  | Optional key-value tags           |

### KubeMQ.QueryReply [#kubemqqueryreply]

Returned by the handler callback.

| Field         | Type                     | Description                          |
| ------------- | ------------------------ | ------------------------------------ |
| `request_id`  | `String.t()`             | Matches the received query ID        |
| `response_to` | `String.t()`             | Matches the reply channel            |
| `executed`    | `boolean()`              | Whether the query succeeded          |
| `body`        | `String.t() \| binary()` | Response data                        |
| `metadata`    | `String.t()`             | Response metadata                    |
| `cache_hit`   | `boolean()`              | Whether the response came from cache |

### KubeMQ.QueryResponse [#kubemqqueryresponse]

Returned to the caller from `send_query/2`.

| Field       | Type                     | Description       |
| ----------- | ------------------------ | ----------------- |
| `query_id`  | `String.t()`             | Query ID          |
| `executed`  | `boolean()`              | Success flag      |
| `body`      | `String.t() \| binary()` | Response data     |
| `metadata`  | `String.t()`             | Response metadata |
| `cache_hit` | `boolean()`              | Cache hit flag    |
| `error`     | `String.t()`             | Error if failed   |

## Command Example [#command-example]

```elixir
{:ok, sub} = KubeMQ.Client.subscribe_to_commands(client, "orders",
  on_command: fn cmd ->
    KubeMQ.CommandReply.new(
      request_id: cmd.id,
      response_to: cmd.reply_channel,
      executed: true
    )
  end
)

cmd = KubeMQ.Command.new(channel: "orders", body: "process", timeout: 10_000)
{:ok, resp} = KubeMQ.Client.send_command(client, cmd)
```

## Query with Caching [#query-with-caching]

```elixir
query = KubeMQ.Query.new(
  channel: "products",
  body: "sku-123",
  timeout: 10_000,
  cache_key: "product-sku-123",
  cache_ttl: 60_000
)

{:ok, resp} = KubeMQ.Client.send_query(client, query)
IO.puts("Cache hit: #{resp.cache_hit}")
```

## See Also [#see-also]

* [RPC Examples](/sdks/elixir/how-to/rpc/)
* [RPC Pattern Overview](/learn/rpc/)