Import from Numpy

Search Shortcut cmd + k | ctrl + k

Documentation / Guides / Python

Import from Numpy

It is possible to query Numpy arrays from DuckDB. There is no need to register the arrays manually – DuckDB can find them in the Python process by name thanks to replacement scans. For example:

import duckdb
import numpy as np

columns = {
    "id": np.array([1, 2, 3]),
    "value": np.array([9.0, 8.0, 7.0]),
}
print(duckdb.sql("SELECT * FROM columns").fetchall())

[(1, 9.0), (2, 8.0), (3, 7.0)]

Each array supplies one column. DuckDB also accepts a two-dimensional array, treating each outer array as a column. Transpose an array whose outer dimension represents rows before querying it.

A masked array is read with its mask: masked elements become NULL.

my_masked_arr = np.ma.masked_array([1.0, 2.0, 3.0], mask=[False, True, False])

duckdb.sql("SELECT * FROM my_masked_arr")

┌─────────┐
│ column0 │
│ double  │
├─────────┤
│     1.0 │
│    NULL │
│     3.0 │
└─────────┘

See Also