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 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 : orientation
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], …) Maximum number of rows to return. Use 0 for no limit.
Number of rows to skip from the beginning. Use 0 to start from the first row.
A dictionary containing the dataset with data and metadata. The structure includes: Schema information for the dataset (same structure as DatasetMetadata ). Array of field objects, where each field has the following properties: The name of the field/column.
The data type of the field (e.g. “string”, “integer”, “float”, “boolean”, “date”, “datetime”).
Human-readable description of the field.
Category of the field (e.g. “dimension”, “measure”, “misc”).
Total number of rows in the complete dataset (before applying limit/offset).
Metadata about the data subset being returned. Hide data_details properties
Actual number of rows in the returned data subset (after applying limit/offset).
The orientation format used for the data (matches the input parameter).
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 squirrels.types import DatasetResult from squirrels import SquirrelsProject sqrl = SquirrelsProject() # Query a dataset result: DatasetResult = await sqrl.dataset( "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 squirrels.types import DatasetResult from squirrels import SquirrelsProject sqrl = SquirrelsProject() result: DatasetResult = await sqrl.dataset( "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, ...]} 
