Client APIs
Directly Accessing DataFrames and Arrow Objects
DuckDB is automatically able to query certain Python variables by referring to their variable name (as if it was a table).
These types include the following: Pandas DataFrame, Polars DataFrame, Polars LazyFrame, NumPy arrays, [relations](#docs:api:python:relational_api), and Arrow objects.
Accessing these is made possible by [replacement scans](#docs:api:c:replacement_scans).  
DuckDB supports querying multiple types of Apache Arrow objects including [tables](https://arrow.apache.org/docs/python/generated/pyarrow.Table.html), [datasets](https://arrow.apache.org/docs/python/generated/pyarrow.dataset.Dataset.html), [RecordBatchReaders](https://arrow.apache.org/docs/python/generated/pyarrow.ipc.RecordBatchStreamReader.html), and [scanners](https://arrow.apache.org/docs/python/generated/pyarrow.dataset.Scanner.html). See the Python [guides](#docs:python:overview::) for more examples.  
```python
import duckdb
import pandas as pd

test_df = pd.DataFrame.from_dict({"i": [1, 2, 3, 4], "j": ["one", "two", "three", "four"]})
print(duckdb.sql("SELECT * FROM test_df").fetchall())
```  
```text
[(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
```  
DuckDB also supports “registering” a DataFrame or Arrow object as a virtual table, comparable to a SQL `VIEW`. This is useful when querying a DataFrame/Arrow object that is stored in another way (as a class variable, or a value in a dictionary). Below is a Pandas example:  
If your Pandas DataFrame is stored in another location, here is an example of manually registering it:  
```python
import duckdb
import pandas as pd

my_dictionary = {}
my_dictionary["test_df"] = pd.DataFrame.from_dict({"i": [1, 2, 3, 4], "j": ["one", "two", "three", "four"]})
duckdb.register("test_df_view", my_dictionary["test_df"])
print(duckdb.sql("SELECT * FROM test_df_view").fetchall())
```  
```text
[(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
```  
You can also create a persistent table in DuckDB from the contents of the DataFrame (or the view):  
```python
# create a new table from the contents of a DataFrame
con.execute("CREATE TABLE test_df_table AS SELECT * FROM test_df")
# insert into an existing table from the contents of a DataFrame
con.execute("INSERT INTO test_df_table SELECT * FROM test_df")
```  
#### Pandas DataFrames – `object` Columns {#docs:api:python:data_ingestion::pandas-dataframes--object-columns}  
`pandas.DataFrame` columns of an `object` dtype require some special care, since this stores values of arbitrary type.
To convert these columns to DuckDB, we first go through an analyze phase before converting the values.
In this analyze phase a sample of all the rows of the column are analyzed to determine the target type.
This sample size is by default set to 1000.
If the type picked during the analyze step is incorrect, this will result in a "Failed to cast value:" error, in which case you will need to increase the sample size.
The sample size can be changed by setting the `pandas_analyze_sample` config option.  
```python
# example setting the sample size to 100k
duckdb.execute("SET GLOBAL pandas_analyze_sample = 100_000")
```  
#### Registering Objects {#docs:api:python:data_ingestion::registering-objects}  
You can register Python objects as DuckDB tables using the [`DuckDBPyConnection.register()` function](#docs:api:python:reference:index::duckdb.DuckDBPyConnection.register).  
The precedence of objects with the same name is as follows:  
* Objects explicitly registered via `DuckDBPyConnection.register()`
* Native DuckDB tables and views
* [Replacement scans](#docs:api:c:replacement_scans)