> ## 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 Parameters Reference
> Complete reference for all parameters accepted by the CloudQuant Data Liberator query function across all SDKs.
# Query parameters reference
This page documents the parameters accepted by the `query` function across all CloudQuant Data Liberator SDKs. Parameter names are consistent across languages; only the types and calling conventions differ.
At least one of the following is required for every query:
* A dataset via `name` **or** a raw `sql` statement.
* A time anchor: `back_to`, `as_of`, `max_lookback` (LKV mode), or `record_limit` (N-Query mode).
Unknown parameters are rejected by the server when strict validation is enabled (the default).
## Time range parameters
| Parameter | Default | Description |
| -------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as_of` | `None` | End time for the query. `None` means "now". Integer values are interpreted as microseconds since epoch; strings are interpreted as datetimes. In N-Query backward mode the boundary is **exclusive** (`muts < as_of`). |
| `back_to` | `None` | Start time for the query. `None` means as-of only (single point in time, or LKV). In N-Query forward mode the boundary is **inclusive** (`muts >= back_to`). |
| `max_lookback` | (from dataset config) | Used for LKV (last-known-value) queries. Integer values **less than 1,000,000** are treated as a number of partitions to look back; values **greater than or equal to 1,000,000** are treated as a duration in microseconds. May be supplied per-query or inherited from dataset config. |
For LKV mode, omit `back_to` and use `as_of` (or the default "now") together with `max_lookback`. For N-Query mode, provide either `as_of` (backward) or `back_to` (forward) along with `record_limit`.
### Date format
Datetime strings use the format `YYYY-MM-DD HH:MM:SS` (the time portion is optional). When the time portion is omitted, `00:00:00` is assumed — for example, `as_of: "2023-01-15"` is interpreted as `as_of: "2023-01-15 00:00:00"`. If `as_of` and `back_to` are identical, the result is a single point rather than a time series.
## Dataset & symbol parameters
| Parameter | Default | Description |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `None` | Dataset name(s). A **string** selects a single dataset; a **list of strings** triggers a superquery (multi-dataset merge). Required unless `sql` is provided. |
| `symbols` | `None` | Symbol(s) to filter on. Accepts a string, a list of strings, or `None` for all symbols in the dataset. |
| `keys` | `None` | Synonym for `symbols`. |
| `fields` | `None` | Field names to return. List of strings or `None` for all fields. Mandatory fields cannot be removed. |
| `distinct` | `["symbol"]` | Partition key for LKV queries: the columns used in `PARTITION BY` (for example, `["symbol"]` or `["symbol", "dataset"]`). |
| `translate` | `None` | When set to `true` or `false`, enables or disables [dataset field mapping](/administration/dataset-field-mapping) lookups configured on the dataset. |
| `where` | `None` | Optional SQL predicate appended to generated filters with `AND`. Omit the `WHERE` keyword — supply only the condition (e.g. `"volume > 1000000"`). Not compatible with `sql`. |
| `sql` | `None` | Raw SQL `SELECT` statement. When present, replaces parameter-based query construction (`name`, time range, `where`, etc.). See [Raw SQL](#raw-sql) below. |
## Custom WHERE filters
The `where` parameter adds extra predicates on top of the time-range and symbol filters CloudQuant Data Liberator generates automatically. The value is appended as `AND ()` to the internal query.
| Aspect | Detail |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| **Syntax** | SQL expression only — no leading `WHERE` |
| **Compatible with** | `name`, `back_to`, `as_of`, `symbols`, `fields`, `record_limit`, LKV (`max_lookback`), N-Query |
| **Incompatible with** | `sql` |
| **Column quoting** | Column names matching the dataset schema are auto-quoted when required |
```python Python theme={null}
result = liberator.query(
name="daily_bars",
symbols=["AAPL"],
back_to="2024-01-01",
as_of="2024-07-01",
where="volume > 1000000"
)
```
```csharp C# theme={null}
var result = liberator.query(new Dictionary() {
{"name", "daily_bars"},
{"symbols", new[] {"AAPL"}},
{"back_to", "2024-01-01"},
{"as_of", "2024-07-01"},
{"where", "volume > 1000000"}
});
```
```r R theme={null}
result <- liberator::query(
name = "daily_bars",
symbols = c("AAPL"),
back_to = "2024-01-01",
as_of = "2024-07-01",
where = "volume > 1000000"
)
```
For multi-key datasets (e.g. concordance tables with a `dataset` column), `where` can filter on columns beyond `symbol`:
```python theme={null}
result = liberator.query(
name="concordance",
back_to="2024-01-01",
as_of="2025-01-01",
where="dataset = 'my_derived_dataset'"
)
```
## Raw SQL
The `sql` parameter accepts a complete SQL `SELECT` and bypasses automatic query construction. Use it when you need direct control over joins, subqueries, or complex predicates.
### Requirements
| Rule | Detail |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Statement type | Must be a `SELECT` (each arm of `UNION` / `INTERSECT` / `EXCEPT` is validated separately) |
| `WHERE` clause | Required on every `SELECT` arm |
| Time-range predicate | By default, `WHERE` must include `=`, `>`, `>=`, `<`, `<=`, or `BETWEEN` on `muts` or columns listed in `LIBERATOR_SQL_TIME_RANGE_COLUMNS` |
| Dataset references | Quote table names with double quotes: `"my_dataset"` |
| String literals | Use `$$value$$` dollar-quoting for symbol and string filters |
| Timestamps | Express `muts` bounds as microsecond integers |
### Parameters allowed with `sql`
When `sql` is supplied, only auth, transfer, and cache options may accompany it. Non-empty construction parameters (`name`, `back_to`, `as_of`, `where`, `fields`, etc.) raise an error.
Allowed alongside `sql`: `user`, `system`, `token`, `compress`, `json_xfer`, `batch_size`, `debug_stream`, `force_regen`, `dependent_partition_name`, `skip_validation`, `skip_discovery`, `symbols`, `symbol_key_sequences`, `data_key_column`.
Do not combine `sql` with `name`, `where`, `back_to`, `as_of`, or other query-construction parameters. Choose parameter-based queries or raw SQL, not both.
## Query limits & ordering
| Parameter | Default | Description |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `record_limit` | `None` | When set to a non-zero integer, triggers **N-Query mode**. **Negative** values (e.g. `-200`) apply a per-symbol limit. **Positive** values (e.g. `200`) apply a global clamp (most recent N records across all symbols). Ignored when both `as_of` and `back_to` are provided. |
| `order` | `None` | Result ordering. One of `"asc_strict"`, `"asc_loose"`, `"desc_strict"`, `"desc_loose"`. Default is ascending. |
### N-query mode
N-Query mode is activated by supplying a non-zero `record_limit`.
* **Anchor:** Backward N-Query uses `as_of` (exclusive); forward N-Query uses `back_to` (inclusive). Exactly one anchor is required.
* **Per-symbol vs global:** A negative `record_limit` returns up to N records per symbol; a positive value returns N records total, distributed by recency.
* **Compatibility:** N-Query works with both single-dataset and superquery queries. When both `as_of` and `back_to` are set, `record_limit` is ignored and a standard time-range query is executed.
## Superquery parameters
A **superquery** is triggered when `name` is a **list** of dataset names. It merges and resamples data from multiple datasets into a single result.
| Parameter | Default | Description |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `superq_resample_rule` | `"1D"` | Resampling interval. Accepts pandas-style strings (e.g. `"5T"`, `"1D"`) or Liberator-native values: fixed (`1s`–`60s`, `1m`–`240m`, `1d`, `7d`) or calendar (`day`, `wk`, `mo`, `qtr`, `yr`). |
| `superq_fill_forward` | `True` | Fill forward missing values. Only `false` is currently supported when using aggregates. |
| `superq_aggregates` | `False` | Aggregation spec. `False` / `None` disables aggregation; a dict provides per-dataset record-level (`last_timestamp`, `first_timestamp`) and column-level aggregates (see below). |
### Column-level aggregate aliases
| Alias | Meaning | Description |
| ----- | ------- | --------------------------- |
| `o` | first | First value in the bucket |
| `h` | high | Maximum value in the bucket |
| `l` | low | Minimum value in the bucket |
| `c` | last | Last value in the bucket |
| `s` | sum | Sum of values in the bucket |
Record-level aggregates (`last_timestamp`, `first_timestamp`) apply to the entire dataset per bucket. Output columns are named `{dataset}_{column}_{alias}` (e.g. `trades_price_o`, `trades_volume_s`) for column-level aggregates, and `{dataset}__first_timestamp` / `{dataset}__last_timestamp` for record-level aggregates.
**Dict format example:**
```json theme={null}
{
"my_dataset": [
"last_timestamp",
"first_timestamp",
{
"price": ["o", "h", "l", "c"],
"volume": ["s"],
"datetime_utc": []
}
]
}
```
## Authentication & authorization
| Parameter | Default | Description |
| --------- | ------- | --------------------------------------------- |
| `user` | `None` | Authorized user name (used for entitlements). |
| `system` | `None` | System identifier. Typically `"API"`. |
| `token` | `None` | Authentication token. |
The `user` and `token` parameters can be provided per-query or configured once at the SDK level:
* **Python:** Set via the `liberator.json` file in your working directory.
* **JavaScript:** Use `liberator.set_default("query", credentials)` to avoid passing them every time.
* **RESTful:** Include in each request's JSON body.
* **Other SDKs:** Loaded from `liberator.json` in the working directory.
## Connection & transfer
| Parameter | Default | Description |
| ------------ | ------- | ---------------------------------------------- |
| `compress` | `False` | Compress the response on the wire. |
| `json_xfer` | `False` | Use JSON transfer format instead of Arrow IPC. |
| `batch_size` | `25000` | Rows per batch for chunked / streaming output. |
## Cache & derived data
| Parameter | Default | Description |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `force_regen` | `False` | Bypass caches (e.g. snapfresh, superquery cache) and regenerate results. |
| `dependent_partition_name` | `None` | Partition UUID for dependency tracking (used for cache invalidation). |
| `skip_validation` | `None` | Tri-state override for cache\_manager validation. When unset, the server default from environment is used. |
| `skip_discovery` | `None` | Tri-state override for partition discovery. When unset, the server default from environment is used. |
## Streaming & debug
| Parameter | Default | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `force_streaming` | `False` | Enable incremental streaming for lower time-to-first-byte. Supported only for single-table, non–N-Query reads. |
| `debug_stream` | `False` | Enable debug / progress output. Language-specific type (e.g. `stderr()` in R, `std::ostream*` in C++, `System.IO.TextWriter` in C#). |
| `warning_stream` | `None` | Output stream for warning information. Same type conventions as `debug_stream`. |
## SDK connection options
These options configure the SDK client rather than the query itself.
| Parameter | Default | Description |
| --------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `url` | From Profile download | CloudQuant Data Liberator server URL. Preconfigured in clients downloaded from your Liberator Profile page. Override for a specific IP or port, e.g. `http://127.0.0.1:47753`. |
## Example queries
### Basic time-range query
```python theme={null}
result = liberator.query(
name="my_dataset",
symbols=["AAPL", "MSFT"],
back_to="2025-01-01 00:00:00",
as_of="2025-01-02 00:00:00",
fields=["Price", "Volume"],
order="asc_strict"
)
```
### LKV (last-known-value) query
```python theme={null}
result = liberator.query(
name="my_dataset",
symbols=["AAPL"],
max_lookback=3 # last 3 partitions
)
```
### N-query: most recent 200 records (backward from `as_of`)
```python theme={null}
result = liberator.query(
name="my_dataset",
symbols=["AAPL"],
record_limit=200,
as_of="2025-01-15 00:00:00"
)
```
### N-query: first 200 records (forward from `back_to`)
```python theme={null}
result = liberator.query(
name="my_dataset",
symbols=["AAPL"],
record_limit=200,
back_to="2025-01-01 00:00:00"
)
```
### N-query per-symbol (negative limit)
```python theme={null}
result = liberator.query(
name="my_dataset",
symbols=["AAPL", "MSFT"],
record_limit=-10, # up to 10 records per symbol
as_of="2025-01-15 00:00:00"
)
```
### Superquery with aggregates
```python theme={null}
result = liberator.query(
name=["dataset1", "dataset2"],
symbols=["AAPL"],
back_to="2021-01-01",
as_of="2021-03-01",
superq_resample_rule="5T",
superq_fill_forward=False,
superq_aggregates={
"dataset1": [
"last_timestamp",
"first_timestamp",
{
"Trade Price": ["o", "h", "l", "c"],
"volume": ["s"]
}
]
}
)
```
### Raw SQL
```python theme={null}
result = liberator.query(
sql='SELECT * FROM "my_dataset" WHERE muts >= 1704067200000000 AND muts < 1704153600000000 AND symbol = $$AAPL$$',
user="my_user",
system="API"
)
```
### Parameter-based query with `where`
```python theme={null}
result = liberator.query(
name="my_dataset",
symbols=["AAPL"],
back_to="2025-01-01 00:00:00",
as_of="2025-01-02 00:00:00",
where="volume > 0",
fields=["Price", "Volume"],
order="asc_strict"
)
```