---
title: "Query Dataset"
method: POST
path: "/felix/dataset/query"
tags: ["felix"]
---

# Query Dataset

`POST /felix/dataset/query`

Execute Polars code on a dataset server-side.

The code runs in a sandboxed environment with access to:
- `df`: Polars DataFrame containing the dataset
- `pl`: Polars module for expressions

Assign the result to a `result` variable to return it.
**Multiline code is fully supported** — use intermediate variables, comments, etc.

**Security**: Only allowlisted Polars DataFrame/Expression methods are
permitted. Control-flow (for/while/if-stmt), comprehensions, f-strings,
str.format, imports, eval/exec, and dunder access are all blocked.

**Examples**::

    result = df.head(10)

    filtered = df.filter(pl.col('score') > 0.5)
    grouped = filtered.group_by('label').agg([
        pl.col('score').mean().alias('avg_score'),
        pl.col('score').count().alias('count')
    ])
    result = grouped.sort('avg_score', descending=True)

## Request body

- DatasetQueryRequest — Request to execute Polars code on a dataset server-side. The code has access to: - `df`: Polars DataFrame containing the dataset - `pl`: Polars module for expressions (pl.col, pl.lit, pl.when, etc.) Assign result to `result` variable to return it. Multi-statement code with intermediate variables is supported. Control-flow (for/while/if-stmt), comprehensions, and f-strings are not available; use ternary expressions (A if cond else B) for conditional results.
  - `dataset_name` string, required — Name of the dataset to query
  - `version` string, nullable — Dataset version (latest if omitted)
  - `code` string, required — Polars code to execute. Access data as 'df'. Assign output to 'result'.
  - `timeout` integer — Execution timeout in seconds (1-120)
  - `max_rows_returned` integer — Maximum rows to return in result (1-100000)

## Response `200`

Successful Response

- DatasetQueryResponse — Response from dataset query execution.
  - `success` boolean, required
  - `dataset_name` string, required
  - `dataset_version` string, required
  - `result` unknown, required
  - `result_type` 'dataframe' | 'series' | 'scalar' | 'string' | 'list' | 'object' | 'none', required — Type of the returned result
  - `row_count` integer, nullable — Number of rows if result is a DataFrame
  - `columns` string[], nullable — Column names if result is a DataFrame
  - `execution_time_ms` integer, required — Execution time in milliseconds
  - `truncated` boolean — Whether result was truncated due to size limits
  - `message` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pioneer/apis/brain-api.md) · [All operations](https://skmtc.net/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pioneer/brain-api/revisions/31dfe831e079/schema)