DatasetResult

Class representing a dataset result including the data and metadata. Extends DatasetMetadata. Instances of DatasetResult are created and returned by Squirrels dataset execution APIs (for example, in dataset routes or project methods); you should not construct this class directly. If DatasetResult is needed for type annotation, it can be imported from the squirrels.types or squirrels module.

Attributes

pl.DataFrame

The dataset as a Polars DataFrame

Methods

to_json()

Returns the dataset as a JSON-serializable dictionary with pagination support.

def to_json(
    self, orientation: Literal["records", "rows", "columns"], 
    limit: int, offset: int
) -> dict:

Hide arguments

Literal["records", "rows", "columns"]

required

How to orient the data in the response. Options:

“records”: Array of objects where each object is a row (e.g., [col1: val1, col2: val2, …])
“rows”: Array of arrays where each inner array is a row (e.g., [[val1, val2], …])
“columns”: Object where keys are column names and values are arrays (e.g., col1: [val1, val2], …)

int

required

Maximum number of rows to return. Use 0 for no limit.

int

required

Number of rows to skip from the beginning. Use 0 to start from the first row.

dict

A dictionary containing the dataset with data and metadata. The structure includes:

Show return structure

object

Schema information for the dataset (same structure as DatasetMetadata).

Hide schema properties

array

Array of field objects, where each field has the following properties:

Hide field properties

string

The name of the field/column.

string

The data type of the field (e.g. “string”, “integer”, “float”, “boolean”, “date”, “datetime”).

string

Human-readable description of the field.

string

Category of the field (e.g. “dimension”, “measure”, “misc”).

int

Total number of rows in the complete dataset (before applying limit/offset).

object

Metadata about the data subset being returned.

Hide data_details properties

int

Actual number of rows in the returned data subset (after applying limit/offset).

string

The orientation format used for the data (matches the input parameter).

array | object

The actual dataset in the requested orientation format. Type depends on the orientation parameter:

“records”: Array of objects
“rows”: Array of arrays
“columns”: Object with column names as keys

Examples

Here are some common usage patterns for the DatasetResult class. It is assumed that the code is running in an async context (e.g. inside an async function or a Jupyter Notebook cell).

Query a dataset and access the dataframe

from typing import TYPE_CHECKING
from squirrels import SquirrelsProject

if TYPE_CHECKING:
    from squirrels.types import DatasetResult

sqrl = SquirrelsProject()

# Query a dataset
result: "DatasetResult" = await sqrl.dataset_result(
    "sales_data",
    selections={"year": "2024", "region": "north-america"}
)

# Access the Polars DataFrame
print(result.df.head())

# Convert to pandas if needed
pandas_df = result.df.to_pandas()

Export dataset to JSON with different orientations

from typing import TYPE_CHECKING
from squirrels import SquirrelsProject

if TYPE_CHECKING:
    from squirrels.types import DatasetResult

sqrl = SquirrelsProject()

result: "DatasetResult" = await sqrl.dataset_result("sales_data")

# Get first 10 rows as array of objects (records orientation)
json_data = result.to_json("records", limit=10, offset=0)
print(json_data['data'])
# Output: [{'date': '2024-01-01', 'amount': 100}, ...]

# Get as array of arrays (rows orientation)
json_data = result.to_json("rows", limit=10, offset=0)
print(json_data['data'])
# Output: [['2024-01-01', 100], ['2024-01-02', 150], ...]

# Get as column-oriented object (columns orientation)
json_data = result.to_json("columns", limit=10, offset=0)
print(json_data['data'])
# Output: {'date': ['2024-01-01', '2024-01-02', ...], 'amount': [100, 150, ...]}

arguments

auth

connections

parameters

parameter_options

data_sources

dashboards

types

Attributes

Methods

to_json()

Examples

Query a dataset and access the dataframe

Export dataset to JSON with different orientations

​Attributes

​Methods

​to_json()

​Examples

​Query a dataset and access the dataframe

​Export dataset to JSON with different orientations

Attributes

Methods

to_json()

Examples

Query a dataset and access the dataframe

Export dataset to JSON with different orientations