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 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 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 (<your clause>) 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

result = liberator.query(
    name="daily_bars",
    symbols=["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:

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:

{
  "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

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

Parameter-based query with `where`

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

​Query parameters reference

​Time range parameters

​Date format

​Dataset & symbol parameters

​Custom WHERE filters

​Raw SQL

​Requirements

​Parameters allowed with sql

​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

​Parameter-based query with where

Query parameters reference

Time range parameters

Date format

Dataset & symbol parameters

Custom WHERE filters

Raw SQL

Requirements

Parameters allowed with `sql`

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

Parameter-based query with `where`