Connection¶

class duckdb.Appender¶

Bases: object

append_row(self, *args) → None¶

Buffer one row, one value per column, each converted as an executemany parameter would be

append_rows(self, rows: object) → None¶

Buffer each row of an iterable of sequences, stopping at the first bad row and keeping the rows before it

clear(self) → None¶

Drop the buffered rows

flush(self) → None¶

Apply the rows buffered since the last flush with one statement on the appender’s connection

class duckdb.DuckDBPyConnection¶

Bases: object

abort(self) → None¶

Cancel the rest of the result of execute(); a statement that may write fails an open transaction

append(self, table_name: str, df: object, *, by_name: bool = False) → _duckdb.DuckDBPyConnection¶

Append the passed DataFrame to the named table

appender(self, table: str, *, columns: list | None = None, action: str = 'insert', key: list | None = None) → _duckdb.Appender¶

Create an appender that buffers rows and inserts, upserts, updates or deletes them in the named table at each flush

array_type(self, type: _duckdb._sqltypes.DuckDBPyType, size: int) → _duckdb._sqltypes.DuckDBPyType¶

Create an array type object of ‘type’

begin(self) → _duckdb.DuckDBPyConnection¶

Start a new transaction

checkpoint(self) → _duckdb.DuckDBPyConnection¶

Synchronizes data in the write-ahead log (WAL) to the database data file (no-op for in-memory connections)

close(self) → None¶

Close the connection

commit(self) → _duckdb.DuckDBPyConnection¶

Commit changes performed within a transaction

complete(self) → None¶

Run the result of execute() to its end without reading its rows

create_function(self, name: str, function: collections.abc.Callable, parameters: object | None = None, return_type: object | None = None, *, type: PythonUDFType = PythonUDFType.NATIVE, null_handling: FunctionNullHandling = FunctionNullHandling.DEFAULT, exception_handling: PythonExceptionHandling = PythonExceptionHandling.DEFAULT, side_effects: bool = False) → _duckdb.DuckDBPyConnection¶

Create a DuckDB function out of the passing in Python function so it can be used in queries

cursor(self) → _duckdb.DuckDBPyConnection¶

Create a duplicate of the current connection

decimal_type(self, width: int, scale: int) → _duckdb._sqltypes.DuckDBPyType¶

Create a decimal type with ‘width’ and ‘scale’

property description¶

Get result set attributes, mainly column names

df(self, *, date_as_object: bool = False) → object¶

Fetch a result as DataFrame following execute()

disable_profiling(self) → None¶

Disable profiling for subsequent queries

dtype(self, type_str: str) → _duckdb._sqltypes.DuckDBPyType¶

Create a type object by parsing the ‘type_str’ string

duplicate(self) → _duckdb.DuckDBPyConnection¶

Create a duplicate of the current connection

enable_profiling(self) → None¶

Enable profiling for subsequent queries

enum_type(self, name: str, type: _duckdb._sqltypes.DuckDBPyType, values: list) → _duckdb._sqltypes.DuckDBPyType¶

Create an enum type of underlying ‘type’, consisting of the list of ‘values’

execute(self, query: object, parameters: object | None = None) → _duckdb.DuckDBPyConnection¶

Execute the given SQL query, optionally using prepared statements with parameters set. A query runs until its first rows are ready, so an error there raises here; every other statement runs to its end

executemany(self, query: object, parameters: object | None = None) → _duckdb.DuckDBPyConnection¶

Execute the given prepared statement multiple times using the list of parameter sets in parameters

extract_statements(self, query: str) → list¶

Parse the query string and extract the Statement object(s) produced

fetch_df(self, *, date_as_object: bool = False) → object¶

Fetch a result as DataFrame following execute()

fetch_df_chunk(self, vectors_per_chunk: int = 1, *, date_as_object: bool = False) → object¶

Fetch a chunk of the result as DataFrame following execute()

fetchall(self) → list¶

Fetch all rows from a result following execute

fetchdf(self, *, date_as_object: bool = False) → object¶

Fetch a result as DataFrame following execute()

fetchmany(self, size: int = 1) → list¶

Fetch the next set of rows from a result following execute

fetchnumpy(self) → dict¶

Fetch a result as list of NumPy arrays following execute

fetchone(self) → object¶

Fetch a single row from a result following execute

filesystem_is_registered(self, name: str) → bool¶

Check if a filesystem with the provided name is currently registered

from_arrow(arrow_object: object) → DuckDBPyRelation¶

Create a relation object from an Arrow object.

from_csv_auto(*args: object, **kwargs: object) → DuckDBPyRelation¶

Create a relation object from the CSV file in ‘name’.

from_df(df: object) → DuckDBPyRelation¶

Create a relation object from the DataFrame in df.

from_parquet(path_or_buffer: object, binary_as_string: bool = False, **kwargs: Any) → DuckDBPyRelation¶

Create a relation object from the Parquet path(s) or file-like object(s) in ‘path_or_buffer’.

from_query(query: object, *, alias: str = '', params: object = None) → DuckDBPyRelation | None¶

Run a SQL query. A statement that only reads returns a relation that runs the query each time it is read, parameter values bound at every run. Any other statement runs once, now, and gives a relation over what it returned. Statements before the last one run immediately.

get_profiling_information(self, format: str = 'json') → str¶

Get profiling information for a query

get_table_names(self, query: str, *, qualified: bool = False) → set[str]¶

Extract the required table names from a query

install_extension(self, extension: str, *, force_install: bool = False, repository: object | None = None, repository_url: object | None = None, version: object | None = None) → None¶

Install an extension by name, with an optional version and/or repository to get the extension from

interrupt(self) → None¶

Interrupt pending operations

list_filesystems(self) → list¶

List registered filesystems, including builtin ones

list_type(self, type: _duckdb._sqltypes.DuckDBPyType) → _duckdb._sqltypes.DuckDBPyType¶

Create a list type object of ‘type’

load_extension(self, extension: str) → None¶

Load an installed extension

map_type(self, key: _duckdb._sqltypes.DuckDBPyType, value: _duckdb._sqltypes.DuckDBPyType) → _duckdb._sqltypes.DuckDBPyType¶

Create a map type object from ‘key_type’ and ‘value_type’

query(query: object, *, alias: str = '', params: object = None) → DuckDBPyRelation | None¶

Run a SQL query. A statement that only reads returns a relation that runs the query each time it is read, parameter values bound at every run. Any other statement runs once, now, and gives a relation over what it returned. Statements before the last one run immediately.

query_appender(self, dml: str, columns: dict, *, source: str | None = None) → _duckdb.Appender¶

Create an appender that buffers rows of the declared columns and runs the DML over them at each flush

query_progress(self) → float¶

Query progress of pending operation

read_csv(*args: object, **kwargs: object) → DuckDBPyRelation¶

Create a relation object from the CSV file in ‘name’.

read_json(path_or_buffer: object, **kwargs: Any) → DuckDBPyRelation¶

Create a relation object from the JSON file in ‘name’.

read_parquet(path_or_buffer: object, binary_as_string: bool = False, **kwargs: Any) → DuckDBPyRelation¶

Create a relation object from the Parquet path(s) or file-like object(s) in ‘path_or_buffer’.

register(self, view_name: str, python_object: object) → _duckdb.DuckDBPyConnection¶

Register the passed Python Object value for querying with a view

register_filesystem(self, filesystem: object | None) → None¶

Register a fsspec compliant filesystem

remove_function(self, name: str) → _duckdb.DuckDBPyConnection¶

Remove a previously created function

rollback(self) → _duckdb.DuckDBPyConnection¶

Roll back changes performed within a transaction

row_type(self, fields: object) → _duckdb._sqltypes.DuckDBPyType¶

Create a struct type object from ‘fields’

property rowcount¶

Get result set row count

sql(query: object, *, alias: str = '', params: object = None) → DuckDBPyRelation | None¶

Run a SQL query. A statement that only reads returns a relation that runs the query each time it is read, parameter values bound at every run. Any other statement runs once, now, and gives a relation over what it returned. Statements before the last one run immediately.

sqltype(self, type_str: str) → _duckdb._sqltypes.DuckDBPyType¶

Create a type object by parsing the ‘type_str’ string

string_type(self, collation: str = '') → _duckdb._sqltypes.DuckDBPyType¶

Create a string type with an optional collation

struct_type(self, fields: object) → _duckdb._sqltypes.DuckDBPyType¶

Create a struct type object from ‘fields’

table(table_name: str) → DuckDBPyRelation¶

Create a relation object for the named table.

table_function(name: str, parameters: object = None) → DuckDBPyRelation¶

Create a relation object from the named table function with given parameters.

tf(self) → dict¶

Fetch a result as dict of TensorFlow Tensors following execute()

to_arrow_reader(batch_size: int = 131072) → Any¶

A reader over every row the pending result still holds.

to_arrow_table(batch_size: int = 131072) → Any¶

Every row the pending result still holds, as an Arrow Table.

torch(self) → dict¶

Fetch a result as dict of PyTorch Tensors following execute()

type(self, type_str: str) → _duckdb._sqltypes.DuckDBPyType¶

Create a type object by parsing the ‘type_str’ string

union_type(self, members: object) → _duckdb._sqltypes.DuckDBPyType¶

Create a union type object from ‘members’

unregister(self, view_name: str) → _duckdb.DuckDBPyConnection¶

Unregister the view name

unregister_filesystem(self, name: str) → None¶

Unregister a filesystem

values(*args: object) → DuckDBPyRelation¶

Create a relation object from the passed values.

view(view_name: str) → DuckDBPyRelation¶

Create a relation object for the named view.

class duckdb.Statement¶

Bases: object

property expected_result_type¶

Get the expected type of result produced by this statement, actual type may vary depending on the statement.

property named_parameters¶

Get the map of named parameters this statement has.

property query¶

Get the query equivalent to this statement.

property type¶

Get the type of the statement.

Relation¶

class duckdb.DuckDBPyRelation(*args: object, **kwargs: object)¶

Bases: object

A query built a step at a time; it runs only when a method reads its rows, and runs again on every read.

Detailed examples can be found at Relational API page.

aggregate(aggr_expr: object, group_expr: object = '') → DuckDBPyRelation¶

Compute the aggregate aggr_expr by the optional groups group_expr on the relation.

Detailed examples can be found at Relational API page.

alias¶

Get the name of the current alias.

Detailed examples can be found at Relational API page.

any_value(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Returns the first non-null value from a given expression.

Detailed examples can be found at Relational API page.

apply(function_name: str, function_aggr: str, group_expr: str = '', function_parameter: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Compute the function of a single column or a list of columns by the optional groups on the relation.

Detailed examples can be found at Relational API page.

arg_max(arg_column: str, value_column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Finds the row with the maximum value for a value column and returns the value of that row for an argument column.

Detailed examples can be found at Relational API page.

arg_min(arg_column: str, value_column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Finds the row with the minimum value for a value column and returns the value of that row for an argument column.

Detailed examples can be found at Relational API page.

arrow(batch_size: int = 131072) → Any¶

Alias of to_arrow_reader(). We recommend using to_arrow_reader() instead.

Detailed examples can be found at Relational API page.

avg(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the average of a given expression.

Detailed examples can be found at Relational API page.

bit_and(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the bitwise AND of all bits present in a given expression.

Detailed examples can be found at Relational API page.

bit_or(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the bitwise OR of all bits present in a given expression.

Detailed examples can be found at Relational API page.

bit_xor(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the bitwise XOR of all bits present in a given expression.

Detailed examples can be found at Relational API page.

bitstring_agg(expression: str, min: int | None = None, max: int | None = None, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes a bitstring with bits set for each distinct value in a given expression.

Detailed examples can be found at Relational API page.

bool_and(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the logical AND of all values present in a given expression.

Detailed examples can be found at Relational API page.

bool_or(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the logical OR of all values present in a given expression.

Detailed examples can be found at Relational API page.

close() → None¶

Does nothing: a relation holds no result.

Detailed examples can be found at Relational API page.

columns¶

Return a list containing the names of the columns of the relation.

Detailed examples can be found at Relational API page.

count(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the number of elements present in a given expression.

Detailed examples can be found at Relational API page.

create(table_name: str) → None¶

Creates a new table named table_name with the contents of the relation object.

The name is table, schema.table or catalog.schema.table, and a part may be double quoted; a name of more than three parts needs SQL (CREATE TABLE AS) for now.

Detailed examples can be found at Relational API page.

create_view(view_name: str, replace: bool = True) → DuckDBPyRelation¶

Creates a view named view_name that refers to the relation object.

Detailed examples can be found at Relational API page.

cross(other_rel: DuckDBPyRelation) → DuckDBPyRelation¶

Create cross/cartesian product of two relational objects.

Detailed examples can be found at Relational API page.

cume_dist(window_spec: str, projected_columns: str = '') → DuckDBPyRelation¶

Computes the cumulative distribution within the partition.

Detailed examples can be found at Relational API page.

dense_rank(window_spec: str, projected_columns: str = '') → DuckDBPyRelation¶

Computes the dense rank within the partition.

Detailed examples can be found at Relational API page.

describe() → DuckDBPyRelation¶

Gives basic statistics (e.g., min, max) and if NULL exists for each column of the relation.

Detailed examples can be found at Relational API page.

description¶

Return the description of the result.

Detailed examples can be found at Relational API page.

df(*, date_as_object: bool = False) → Any¶

Execute and fetch all rows as a pandas DataFrame.

Detailed examples can be found at Relational API page.

distinct(on: object = None) → DuckDBPyRelation¶

Retrieve distinct rows from this relation object, or the first row of each distinct value of on.

Detailed examples can be found at Relational API page.

drop(*columns: str) → DuckDBPyRelation¶

Remove columns.

Detailed examples can be found at Relational API page.

dtypes¶

Return a list containing the types of the columns of the relation.

Detailed examples can be found at Relational API page.

except_(other_rel: DuckDBPyRelation) → DuckDBPyRelation¶

Create the set except of this relation object with another relation object in other_rel.

Detailed examples can be found at Relational API page.

explain(type: object = ExplainType.STANDARD, format: str | None = None, *, analyze: bool = False) → str¶

The plan the engine runs for this relation, as text; under Jupyter the default is shown as HTML.

Detailed examples can be found at Relational API page.

favg(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the average of all values present in a given expression using a more accurate floating point summation (Kahan Sum).

Detailed examples can be found at Relational API page.

fetch_arrow_reader(batch_size: int = 131072) → Any¶

Deprecated: use to_arrow_reader() instead.

Detailed examples can be found at Relational API page.

fetch_arrow_table(batch_size: int = 131072) → Any¶

Deprecated: use to_arrow_table() instead.

Detailed examples can be found at Relational API page.

fetch_record_batch(rows_per_batch: int = 131072) → Any¶

Deprecated: use to_arrow_reader() instead.

Detailed examples can be found at Relational API page.

fetchall() → builtins.list[tuple[Any, ...]]¶

Execute and fetch all rows as a list of tuples.

Detailed examples can be found at Relational API page.

fetchdf(*, date_as_object: bool = False) → Any¶

Execute and fetch all rows as a pandas DataFrame.

Detailed examples can be found at Relational API page.

fetchnumpy() → dict[str, Any]¶

Execute and fetch all rows as a Python dict mapping each column to one numpy arrays.

Detailed examples can be found at Relational API page.

filter(filter_expr: object) → DuckDBPyRelation¶

Filter the relation object by the filter in filter_expr.

Detailed examples can be found at Relational API page.

first(expression: str, groups: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Returns the first value of a given expression.

Detailed examples can be found at Relational API page.

first_value(expression: str, window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the first value within the group or partition.

Detailed examples can be found at Relational API page.

fsum(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sum of all values present in a given expression using a more accurate floating point summation (Kahan Sum).

Detailed examples can be found at Relational API page.

geomean(expression: str, groups: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the geometric mean over all values present in a given expression.

Detailed examples can be found at Relational API page.

group_by(*columns: object) → GroupedRelation¶

Begin a grouped aggregation; continue with .agg(…).

Detailed examples can be found at Relational API page.

head(n: int = 5) → DuckDBPyRelation¶

The first n rows.

Detailed examples can be found at Relational API page.

histogram(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the histogram over all values present in a given expression.

Detailed examples can be found at Relational API page.

insert(values: object) → None¶

Inserts the given values into the relation.

Detailed examples can be found at Relational API page.

insert_into(table_name: str) → None¶

Inserts the relation object into an existing table named table_name.

The name is table, schema.table or catalog.schema.table, and a part may be double quoted; a name of more than three parts needs SQL (INSERT INTO) for now.

Detailed examples can be found at Relational API page.

intersect(other_rel: DuckDBPyRelation) → DuckDBPyRelation¶

Create the set intersection of this relation object with another relation object in other_rel.

Detailed examples can be found at Relational API page.

iter_rows(batch_size: int = 1024) → Iterator[tuple[Any, ...]]¶

Every row, a batch at a time, over one run of the relation.

The rows are read once into the engine’s memory, so every batch comes from the same run and the connection is free between batches; the caller holds one batch at a time rather than the whole result.

Detailed examples can be found at Relational API page.

join(other_rel: object, condition: object = None, how: str = 'inner', suffix: str | None = None) → DuckDBPyRelation¶

Join the relation object with another relation object in other_rel.

The condition is SQL text, a column name or a list of them for a USING join, an Expression, or a function of the two sides. Types supported are ‘inner’, ‘left’, ‘right’, ‘outer’, ‘full’, ‘semi’, ‘anti’, ‘cross’, ‘positional’, ‘natural’ and ‘asof’. With suffix, a column of the right side whose name the left side already has is renamed with the suffix appended.

Detailed examples can be found at Relational API page.

lag(expression: str, window_spec: str, offset: int = 1, default_value: str = 'NULL', ignore_nulls: bool = False, projected_columns: str = '') → DuckDBPyRelation¶

Computes the lag within the partition.

Detailed examples can be found at Relational API page.

last(expression: str, groups: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Returns the last value of a given expression.

Detailed examples can be found at Relational API page.

last_value(expression: str, window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the last value within the group or partition.

Detailed examples can be found at Relational API page.

lead(expression: str, window_spec: str, offset: int = 1, default_value: str = 'NULL', ignore_nulls: bool = False, projected_columns: str = '') → DuckDBPyRelation¶

Computes the lead within the partition.

Detailed examples can be found at Relational API page.

limit(n: int, offset: int = 0) → DuckDBPyRelation¶

Only retrieve the first n rows from this relation object, starting at offset.

Detailed examples can be found at Relational API page.

list(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Returns a list containing all values present in a given expression.

Detailed examples can be found at Relational API page.

map(map_function: Callable[..., Any], *, schema: object = None) → DuckDBPyRelation¶

Calls the passed function on the relation.

Detailed examples can be found at Relational API page.

materialize() → DuckDBPyRelation¶

Execute once and return a relation over the rows, held in client memory.

Detailed examples can be found at Relational API page.

max(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Returns the maximum value present in a given expression.

Detailed examples can be found at Relational API page.

mean(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the average of a given expression.

Detailed examples can be found at Relational API page.

median(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the median over all values present in a given expression.

Detailed examples can be found at Relational API page.

min(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Returns the minimum value present in a given expression.

Detailed examples can be found at Relational API page.

mode(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the mode over all values present in a given expression.

Detailed examples can be found at Relational API page.

n_tile(window_spec: str, num_buckets: int, projected_columns: str = '') → DuckDBPyRelation¶

Divides the partition as equally as possible into num_buckets.

Detailed examples can be found at Relational API page.

nth_value(expression: str, window_spec: str, offset: int, ignore_nulls: bool = False, projected_columns: str = '') → DuckDBPyRelation¶

Computes the nth value within the partition.

Detailed examples can be found at Relational API page.

offset(n: int) → DuckDBPyRelation¶

Skip n rows.

Detailed examples can be found at Relational API page.

order(order_expr: object) → DuckDBPyRelation¶

Reorder the relation object by order_expr, which is SQL order text or an expression.

Detailed examples can be found at Relational API page.

percent_rank(window_spec: str, projected_columns: str = '') → DuckDBPyRelation¶

Computes the relative rank within the partition.

Detailed examples can be found at Relational API page.

pivot(column: object, values: Iterable[object], aggregate: object) → DuckDBPyRelation¶

Turn the given values of column into columns holding aggregate; the values are explicit.

Detailed examples can be found at Relational API page.

pl(batch_size: int = 131072, *, lazy: bool = False) → Any¶

Execute and fetch all rows as a Polars DataFrame.

Detailed examples can be found at Relational API page.

preview(limit: int = 10) → str¶

The first limit rows drawn as a table, with the footer __repr__ prints for the relation.

Detailed examples can be found at Relational API page.

product(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Returns the product of all values present in a given expression.

Detailed examples can be found at Relational API page.

project(*args: object, groups: str = '') → DuckDBPyRelation¶

Project the relation object by the projection in project_expr.

Detailed examples can be found at Relational API page.

quantile(expression: str, q: float | builtins.list[float] = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the exact quantile value for a given expression.

Detailed examples can be found at Relational API page.

quantile_cont(expression: str, q: float | builtins.list[float] = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the interpolated quantile value for a given expression.

Detailed examples can be found at Relational API page.

quantile_disc(expression: str, q: float | builtins.list[float] = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the exact quantile value for a given expression.

Detailed examples can be found at Relational API page.

query(virtual_table_name: str, sql_query: str) → DuckDBPyRelation | None¶

Run the given SQL query in sql_query on the view named virtual_table_name that refers to the relation object.

The name is this query’s own: it is a common table expression over the relation, and a catalog entry for the length of the call, so a table function or a query that defines the name itself can bind against it. Nothing of it is left afterwards. A statement that does not only read, which includes a SELECT whose common table expression writes, runs at the call and the relation holds what it returned.

Detailed examples can be found at Relational API page.

rank(window_spec: str, projected_columns: str = '') → DuckDBPyRelation¶

Computes the rank within the partition.

Detailed examples can be found at Relational API page.

rank_dense(window_spec: str, projected_columns: str = '') → DuckDBPyRelation¶

Computes the dense rank within the partition.

Detailed examples can be found at Relational API page.

rename(**columns: str) → DuckDBPyRelation¶

Rename columns, given as old=new.

Detailed examples can be found at Relational API page.

row_number(window_spec: str, projected_columns: str = '') → DuckDBPyRelation¶

Computes the row number within the partition.

Detailed examples can be found at Relational API page.

sample(n: int | None = None, *, percent: float | None = None, seed: int | None = None, method: str | None = None) → DuckDBPyRelation¶

A random subset: n rows, or percent of them, with seed repeating a draw.

Detailed examples can be found at Relational API page.

select(*args: object, groups: str = '') → DuckDBPyRelation¶

Project the relation object by the projection in project_expr.

Detailed examples can be found at Relational API page.

select_dtypes(types: object) → DuckDBPyRelation¶

Select columns from the relation, by filtering based on type(s).

Detailed examples can be found at Relational API page.

select_types(types: object) → DuckDBPyRelation¶

Select columns from the relation, by filtering based on type(s).

Detailed examples can be found at Relational API page.

set_alias(alias: str) → DuckDBPyRelation¶

Rename the relation object to new alias.

Detailed examples can be found at Relational API page.

shape¶

Tuple of # of rows, # of columns in relation.

Detailed examples can be found at Relational API page.

show(*, max_width: int | None = None, max_rows: int | None = None, max_col_width: int | None = None, null_value: str | None = None, render_mode: object = None) → None¶

Display a summary of the data.

Detailed examples can be found at Relational API page.

sort(*args: object) → DuckDBPyRelation¶

Reorder the relation object by the provided expressions.

Detailed examples can be found at Relational API page.

sql_query() → str¶

Get the SQL query that is equivalent to the relation; values given as params= stay markers.

Detailed examples can be found at Relational API page.

std(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sample standard deviation for a given expression.

Detailed examples can be found at Relational API page.

stddev(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sample standard deviation for a given expression.

Detailed examples can be found at Relational API page.

stddev_pop(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the population standard deviation for a given expression.

Detailed examples can be found at Relational API page.

stddev_samp(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sample standard deviation for a given expression.

Detailed examples can be found at Relational API page.

string_agg(expression: str, sep: str = ',', groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Concatenates the values present in a given expression with a separator.

Detailed examples can be found at Relational API page.

sum(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sum of all values present in a given expression.

Detailed examples can be found at Relational API page.

tf() → dict[str, Any]¶

Fetch a result as dict of TensorFlow Tensors.

Detailed examples can be found at Relational API page.

to_arrow_reader(batch_size: int = 131072) → Any¶

Execute and return an Arrow Record Batch Reader that yields all rows.

Detailed examples can be found at Relational API page.

to_arrow_table(batch_size: int = 131072) → Any¶

Execute and fetch all rows as an Arrow Table.

Detailed examples can be found at Relational API page.

to_csv(file_name: str, *, sep: str | None = None, na_rep: str | None = None, header: bool | None = None, quotechar: str | None = None, escapechar: str | None = None, date_format: str | None = None, timestamp_format: str | None = None, quoting: str | int | None = None, encoding: str | None = None, compression: str | None = None, overwrite: bool | None = None, per_thread_output: bool | None = None, use_tmp_file: bool | None = None, partition_by: builtins.list[str] | None = None, write_partition_columns: bool | None = None) → None¶

Write the relation object to a CSV file in ‘file_name’.

Detailed examples can be found at Relational API page.

to_df(*, date_as_object: bool = False) → Any¶

Execute and fetch all rows as a pandas DataFrame.

Detailed examples can be found at Relational API page.

to_dicts() → builtins.list[dict[str, Any]]¶

Every row, as a dict keyed by column name.

Detailed examples can be found at Relational API page.

to_parquet(file_name: str, *, compression: str | None = None, field_ids: object = None, row_group_size_bytes: int | str | None = None, row_group_size: int | None = None, overwrite: bool | None = None, per_thread_output: bool | None = None, use_tmp_file: bool | None = None, partition_by: builtins.list[str] | None = None, write_partition_columns: bool | None = None, append: bool | None = None, filename_pattern: str | None = None, file_size_bytes: str | int | None = None) → None¶

Write the relation object to a Parquet file in ‘file_name’.

Detailed examples can be found at Relational API page.

to_table(table_name: str) → None¶

Creates a new table named table_name with the contents of the relation object.

The name is table, schema.table or catalog.schema.table, and a part may be double quoted; a name of more than three parts needs SQL (CREATE TABLE AS) for now.

Detailed examples can be found at Relational API page.

to_view(view_name: str, replace: bool = True) → DuckDBPyRelation¶

Creates a view named view_name that refers to the relation object.

Detailed examples can be found at Relational API page.

torch() → dict[str, Any]¶

Fetch a result as dict of PyTorch Tensors.

Detailed examples can be found at Relational API page.

type¶

Get the type of the relation.

Detailed examples can be found at Relational API page.

types¶

Return a list containing the types of the columns of the relation.

Detailed examples can be found at Relational API page.

union(union_rel: DuckDBPyRelation) → DuckDBPyRelation¶

Create the set union of this relation object with another relation object in other_rel.

Detailed examples can be found at Relational API page.

union_by_name(other: DuckDBPyRelation, *, all: bool = True) → DuckDBPyRelation¶

Rows from both relations, matching columns by name; keeps duplicates unless all is false.

Detailed examples can be found at Relational API page.

unique(unique_aggr: str) → DuckDBPyRelation¶

Returns the distinct values in a column.

Detailed examples can be found at Relational API page.

unnest(*columns: str) → DuckDBPyRelation¶

Expand list columns to one row per element.

Detailed examples can be found at Relational API page.

unpivot(*columns: str, name: str = 'name', value: str = 'value') → DuckDBPyRelation¶

Turn the named columns into rows; name and value name the two new columns.

Detailed examples can be found at Relational API page.

update(set: object, *, condition: object = None) → None¶

Update the given relation with the provided expressions.

Detailed examples can be found at Relational API page.

value_counts(expression: str, groups: str = '') → DuckDBPyRelation¶

Computes the number of elements present in a given expression, also projecting the original expression.

Detailed examples can be found at Relational API page.

var(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sample variance for a given expression.

Detailed examples can be found at Relational API page.

var_pop(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the population variance for a given expression.

Detailed examples can be found at Relational API page.

var_samp(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sample variance for a given expression.

Detailed examples can be found at Relational API page.

variance(expression: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → DuckDBPyRelation¶

Computes the sample variance for a given expression.

Detailed examples can be found at Relational API page.

with_columns(**columns: object) → DuckDBPyRelation¶

Add columns, replacing any of the same name in place.

Detailed examples can be found at Relational API page.

write_csv(file_name: str, *, sep: str | None = None, na_rep: str | None = None, header: bool | None = None, quotechar: str | None = None, escapechar: str | None = None, date_format: str | None = None, timestamp_format: str | None = None, quoting: str | int | None = None, encoding: str | None = None, compression: str | None = None, overwrite: bool | None = None, per_thread_output: bool | None = None, use_tmp_file: bool | None = None, partition_by: builtins.list[str] | None = None, write_partition_columns: bool | None = None) → None¶

Write the relation object to a CSV file in ‘file_name’.

Detailed examples can be found at Relational API page.

write_parquet(file_name: str, *, compression: str | None = None, field_ids: object = None, row_group_size_bytes: int | str | None = None, row_group_size: int | None = None, overwrite: bool | None = None, per_thread_output: bool | None = None, use_tmp_file: bool | None = None, partition_by: builtins.list[str] | None = None, write_partition_columns: bool | None = None, append: bool | None = None, filename_pattern: str | None = None, file_size_bytes: str | int | None = None) → None¶

Write the relation object to a Parquet file in ‘file_name’.

Detailed examples can be found at Relational API page.