> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamosql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Formats

> Choose between row arrays and key-value objects.

DynamoSQL supports two shapes for the `data` field in an execute-mode response. Set `options.responseType` in the request body to control which you receive.

## Row Format (default)

`"responseType": "row"` — `data` is an array of arrays. Each inner array is one row; values are ordered to match the `columns` array.

This format is compact and well-suited for tabular display, streaming to a spreadsheet, or passing into a table-rendering component.

## Object Format

`"responseType": "object"` — `data` is an array of objects. Each object maps column names to their values.

This format is more ergonomic in dynamic languages where you want to access fields by name without tracking column positions manually.

## Both Formats Include

* `columns` — ordered array of column name strings
* `firstRowIdx` — absolute offset of the first row in this page (always `0` on the first page)
* `resumeIdx` — present when more rows exist; pass as `options.resumeIdx` on the next request
* `planTime` — parse + plan + optimize time in milliseconds
* `execTime` — total elapsed time including DynamoDB I/O in milliseconds

## Example

**Request:**

```json theme={null}
{
  "sql": "SELECT id, name FROM myschema.users LIMIT 2",
  "mode": "execute",
  "options": {
    "responseType": "row"
  }
}
```

<CodeGroup>
  ```json Row format (default) theme={null}
  {
    "success": true,
    "data": {
      "columns": ["id", "name"],
      "data": [
        ["u-001", "Alice"],
        ["u-002", "Bob"]
      ],
      "firstRowIdx": 0,
      "planTime": 2,
      "execTime": 18
    }
  }
  ```

  ```json Object format theme={null}
  {
    "success": true,
    "data": {
      "columns": ["id", "name"],
      "data": [
        { "id": "u-001", "name": "Alice" },
        { "id": "u-002", "name": "Bob" }
      ],
      "firstRowIdx": 0,
      "planTime": 2,
      "execTime": 18
    }
  }
  ```
</CodeGroup>

<Note>
  Response format has no effect in plan mode. Plan responses always use the plan result shape (`plan`, `weight`, `normalizedSql`, `planTime`) regardless of `responseType`.
</Note>