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

# Query Parameter Combinations

> A summary of all CloudQuant Data Liberator query parameters and how different combinations affect the results you receive.

# Query parameter combinations

This guide explains the main parameters for CloudQuant Data Liberator queries and the expected results from different combinations.

## Core parameters

| Parameter | Description                                                                     | Default              |
| --------- | ------------------------------------------------------------------------------- | -------------------- |
| `name`    | Dataset identifier (required)                                                   | --                   |
| `symbols` | Single symbol or list, e.g. `['AAPL','GOOG','MSFT']`                            | `None` (all symbols) |
| `back_to` | Query start date                                                                | `None`               |
| `as_of`   | Query end date                                                                  | Current date/time    |
| `fields`  | Specify desired columns to reduce download time                                 | All columns          |
| `stats`   | Set to `'Total'` for symbol counts instead of full results                      | --                   |
| `where`   | Custom SQL predicate appended to the generated filters                          | `None`               |
| `sql`     | Full raw SQL query (replaces `name`, time range, and other construction params) | `None`               |

<Tip>
  Use `liberator.datasets(entitled=True)` to list all datasets available to you.
</Tip>

See the [Query Parameters Reference](/api-reference/concepts/query-parameters) for the full parameter list, including superquery, N-Query, and authentication options.

## Query examples

### All parameters included

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    name = 'daily_bars',
    as_of = '2024-07-24',
    back_to = '2024-07-16',
    symbols = ['AAPL', 'GOOGL']))
```

Returns data for specified symbols within the date range.

### Without symbols

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    name = 'daily_bars',
    as_of = '2024-07-24',
    back_to = '2024-07-16'))
```

Defaults to all available symbols.

### Without `as_of`

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    name = 'daily_bars',
    back_to = '2024-07-22'))
```

Defaults `as_of` to current time, returning data from present back to specified date.

### Without `back_to`

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    name = 'daily_bars',
    as_of = '2023-12-25'))
```

Returns the most recent data point per symbol as of the specified date. Look-back distance varies by dataset density.

### Minimal query (name only)

```python theme={null}
df = liberator.get_dataframe(liberator.query(name = 'daily_bars'))
```

Returns the latest data point for all symbols in the dataset.

## Custom `where` filters

Use `where` with a standard parameter-based query to append extra SQL predicates on top of the filters CloudQuant Data Liberator generates for time range and symbols. The clause is combined with `AND` — do not include the `WHERE` keyword.

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    name='daily_bars',
    as_of='2024-07-24',
    back_to='2024-07-16',
    symbols=['AAPL', 'GOOGL'],
    where='volume > 1000000'
))
```

`where` works with time-range, LKV, and N-Query modes. Column names that match the dataset schema are automatically quoted when needed.

### Multi-dataset / concordance-style filters

For datasets keyed by more than symbol (for example concordance tables with a `dataset` column), use `where` to narrow the result set:

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    name='concordance',
    as_of='2025-01-01',
    back_to='2024-01-01',
    where="dataset = 'my_derived_dataset'"
))
```

<Note>
  `where` cannot be combined with `sql`. Use one approach or the other.
</Note>

## Raw `sql` queries

Pass a complete SQL `SELECT` statement via `sql` instead of `name`, `back_to`, `as_of`, and related parameters. When `sql` is present, parameter-based query construction is skipped.

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    sql='''
        SELECT *
        FROM "daily_bars"
        WHERE muts >= 1704067200000000
          AND muts < 1704153600000000
          AND symbol = $$AAPL$$
    ''',
    user='my_user',
    system='API'
))
```

### SQL requirements

* The statement must be a **`SELECT`** (including `UNION` / `INTERSECT` / `EXCEPT` branches).
* Every `SELECT` arm must include an explicit **`WHERE`** clause.
* By default, the `WHERE` clause must include a **time-range predicate** on `muts` or another configured column (`=`, `>`, `>=`, `<`, `<=`, or `BETWEEN`). Use microsecond timestamps for `muts` values.
* Quote dataset names with double quotes when they contain special characters.
* Use `$$symbol$$` dollar-quoting for string literals in filters.

### Parameters allowed with `sql`

When using `sql`, only connection, auth, and transfer options are permitted alongside the statement — for example `user`, `system`, `token`, `compress`, `json_xfer`, and `batch_size`. Supplying non-empty values for `name`, `back_to`, `as_of`, `where`, or other construction parameters raises an error.

<Warning>
  Raw SQL bypasses the convenience of `name` / `symbols` / `back_to` / `as_of`. Prefer parameter-based queries unless you need full control over the generated SQL.
</Warning>