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

# query

> Commands for executing SQL queries against a connection.

The `query` command group lets you execute SQL queries against a saved connection.

***

## query sql

Executes a SQL query and returns results as JSON.

```bash theme={null}
cdatacli query sql --connection <connection-name> --sql <query>
```

**Options**

| Option         | Description                                                                          | Required |
| -------------- | ------------------------------------------------------------------------------------ | -------- |
| `--connection` | Name of the saved connection to query                                                | Yes      |
| `--sql`        | SQL statement to execute                                                             | Yes      |
| `--timeout`    | Query timeout in seconds (default: 30)                                               | No       |
| `--max-rows`   | Maximum rows returned per result set (default: 1000)                                 | No       |
| `--metadata`   | Include column metadata in the result. By default, only the `resultset` is returned. | No       |

**Examples**

Run a SELECT query:

```bash theme={null}
cdatacli query sql --connection "my-jira" --sql "SELECT Id, Summary FROM Issues LIMIT 2"
```

**Output** (pretty-printed by default)

By default, the output contains only the `resultset` array:

```json theme={null}
{
  "resultset" : [ {
    "Id" : 43147,
    "Summary" : "Add authentication options for enterprise customers"
  }, {
    "Id" : 43148,
    "Summary" : "Improve performance of the editor"
  } ]
}
```

Use `--compact` for single-line output, suitable for piping to tools like `jq`:

```bash theme={null}
cdatacli query sql --connection "my-jira" --sql "SELECT Id, Summary FROM Issues LIMIT 2" --compact
```

```json theme={null}
{"resultset":[{"Id":43147,"Summary":"Add authentication options for enterprise customers"},{"Id":43148,"Summary":"Improve performance of the editor"}]}
```

### Including column metadata

By default, the output omits the column metadata. Add `--metadata` to include a `metadata` array that describes each column returned:

```bash theme={null}
cdatacli query sql --connection "my-jira" --sql "SELECT Id, Summary FROM Issues LIMIT 2" --metadata
```

```json theme={null}
{
  "metadata" : [ {
    "index" : 1,
    "label" : "Id",
    "name" : "Id",
    "jdbcType" : 4,
    "typeName" : "INT",
    "nullable" : false,
    "precision" : 10,
    "scale" : 0,
    "displaySize" : 11,
    "tableName" : "Issues",
    "schemaName" : "JIRA",
    "catalogName" : "CData",
    "autoIncrement" : false,
    "readOnly" : true
  }, {
    "index" : 2,
    "label" : "Summary",
    "name" : "Summary",
    "jdbcType" : 12,
    "typeName" : "VARCHAR",
    "nullable" : false,
    "precision" : 2000,
    "scale" : 0,
    "displaySize" : 2000,
    "tableName" : "Issues",
    "schemaName" : "JIRA",
    "catalogName" : "CData",
    "autoIncrement" : false,
    "readOnly" : false
  } ],
  "resultset" : [ {
    "Id" : 43147,
    "Summary" : "Add authentication options for enterprise customers"
  }, {
    "Id" : 43148,
    "Summary" : "Improve performance of the editor"
  } ]
}
```

## Output format

Query results are returned as a JSON object. By default, it contains a single top-level key, `resultset`, an array of the rows returned by the driver. When you pass `--metadata`, the object also includes a `metadata` key that describes the columns returned.

See [Output format](../output.mdx) for more details on the JSON output structure.