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.
`sql`	`None`	Raw SQL. When present, replaces parameter-based query construction (`name`, time range, etc. are not used).
`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, applies field translation from the dataset config (e.g. display names or units).
`where`	`None`	Optional custom WHERE clause appended to the generated filters.

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:

{
  "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`	`https://api.cloudquant.ai`	CloudQuant Data Liberator server URL. Can be overridden to a specific IP or port, e.g. `http://127.0.0.1:47753`.

Example Queries

Basic Time-Range Query

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

result = liberator.query(
    name="my_dataset",
    symbols=["AAPL"],
    max_lookback=3  # last 3 partitions
)

N-Query: Most Recent 200 Records (Backward from `as_of`)

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`)

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)

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

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

result = liberator.query(
    sql='SELECT * FROM "my_dataset" WHERE muts >= 1704067200000000 AND muts < 1704153600000000 AND symbol = $$AAPL$$',
    user="my_user",
    system="API"
)

​Query Parameters Reference

​Time Range Parameters

​Date Format

​Dataset & Symbol Parameters

​Query Limits & Ordering

​N-Query Mode

​Superquery Parameters

​Column-Level Aggregate Aliases

​Authentication & Authorization

​Connection & Transfer

​Cache & Derived Data

​Streaming & Debug

​SDK Connection Options

​Example Queries

​Basic Time-Range Query

​LKV (Last-Known-Value) Query

​N-Query: Most Recent 200 Records (Backward from as_of)

​N-Query: First 200 Records (Forward from back_to)

​N-Query Per-Symbol (Negative Limit)

​Superquery with Aggregates

​Raw SQL

Query Parameters Reference

Time Range Parameters

Date Format

Dataset & Symbol Parameters

Query Limits & Ordering

N-Query Mode

Superquery Parameters

Column-Level Aggregate Aliases

Authentication & Authorization

Connection & Transfer

Cache & Derived Data

Streaming & Debug

SDK Connection Options

Example Queries

Basic Time-Range Query

LKV (Last-Known-Value) Query

N-Query: Most Recent 200 Records (Backward from `as_of`)

N-Query: First 200 Records (Forward from `back_to`)

N-Query Per-Symbol (Negative Limit)

Superquery with Aggregates

Raw SQL