import pointblank as pb
small_table_polars = pb.load_dataset("small_table")
pb.preview(small_table_polars)PolarsRows13Columns8 |
||||||||
preview()function
Display a table preview that shows some rows from the top, some from the bottom.
USAGE
preview(
data,
columns_subset=None,
n_head=5,
n_tail=5,
limit=50,
show_row_numbers=True,
max_col_width=250,
min_tbl_width=500,
incl_header=None,
)To get a quick look at the data in a table, we can use the preview() function to display a preview of the table. The function shows a subset of the rows from the start and end of the table, with the number of rows from the start and end determined by the n_head= and n_tail= parameters (set to 5 by default). This function works with any table that is supported by the pointblank library, including Pandas, Polars, and Ibis backend tables (e.g., DuckDB, MySQL, PostgreSQL, SQLite, Parquet, etc.).
The view is optimized for readability, with column names and data types displayed in a compact format. The column widths are sized to fit the column names, dtypes, and column content up to a configurable maximum width of max_col_width= pixels. The table can be scrolled horizontally to view even very large datasets. Since the output is a Great Tables (GT) object, it can be further customized using the great_tables API.
Parameters
data :FrameT|Any-
The table to preview, which could be a DataFrame object, an Ibis table object, a CSV file path, a Parquet file path, or a database connection string. When providing a CSV or Parquet file path (as a string or
pathlib.Pathobject), the file will be automatically loaded using an available DataFrame library (Polars or Pandas). Parquet input also supports glob patterns, directories containing .parquet files, and Spark-style partitioned datasets. Connection strings enable direct database access via Ibis with optional table specification using the::table_namesuffix. Read the Supported Input Table Types section for details on the supported table types. columns_subset :str|list[str] |Column| None = None-
The columns to display in the table, by default
None(all columns are shown). This can be a string, a list of strings, aColumnobject, or aColumnSelectorobject. The latter two options allow for more flexible column selection using column selector functions. Errors are raised if the column names provided don’t match any columns in the table (when provided as a string or list of strings) or if column selector expressions don’t resolve to any columns. n_head :int= 5-
The number of rows to show from the start of the table. Set to
5by default. n_tail :int= 5-
The number of rows to show from the end of the table. Set to
5by default. limit :int= 50-
The limit value for the sum of
n_head=andn_tail=(the total number of rows shown). If the sum ofn_head=andn_tail=exceeds the limit, an error is raised. The default value is50. show_row_numbers :bool= True-
Should row numbers be shown? The numbers shown reflect the row numbers of the head and tail in the input
data=table. By default, this is set toTrue. max_col_width :int= 250-
The maximum width of the columns (in pixels) before the text is truncated. The default value is
250("250px"). min_tbl_width :int= 500-
The minimum width of the table in pixels. If the sum of the column widths is less than this value, the all columns are sized up to reach this minimum width value. The default value is
500("500px"). incl_header :bool= None-
Should the table include a header with the table type and table dimensions? Set to
Trueby default.
Returns
GT-
A GT object that displays the preview of the table.
Supported Input Table Types
The data= parameter can be given any of the following table types:
- Polars DataFrame (
"polars") - Pandas DataFrame (
"pandas") - DuckDB table (
"duckdb")* - MySQL table (
"mysql")* - PostgreSQL table (
"postgresql")* - SQLite table (
"sqlite")* - Microsoft SQL Server table (
"mssql")* - Snowflake table (
"snowflake")* - Databricks table (
"databricks")* - PySpark table (
"pyspark")* - BigQuery table (
"bigquery")* - Parquet table (
"parquet")* - CSV files (string path or
pathlib.Pathobject with.csvextension) - Parquet files (string path,
pathlib.Pathobject, glob pattern, directory with.parquetextension, or partitioned dataset) - Database connection strings (URI format with optional table specification)
The table types marked with an asterisk need to be prepared as Ibis tables (with type of ibis.expr.types.relations.Table). Furthermore, using preview() with these types of tables requires the Ibis library (v9.5.0 or above) to be installed. If the input table is a Polars or Pandas DataFrame, the availability of Ibis is not needed.
To use a CSV file, ensure that a string or pathlib.Path object with a .csv extension is provided. The file will be automatically detected and loaded using the best available DataFrame library. The loading preference is Polars first, then Pandas as a fallback.
Connection strings follow database URL formats and must also specify a table using the ::table_name suffix. Examples include:
"duckdb:///path/to/database.ddb::table_name"
"sqlite:///path/to/database.db::table_name"
"postgresql://user:password@localhost:5432/database::table_name"
"mysql://user:password@localhost:3306/database::table_name"
"bigquery://project/dataset::table_name"
"snowflake://user:password@account/database/schema::table_name"When using connection strings, the Ibis library with the appropriate backend driver is required.
Examples
It’s easy to preview a table using the preview() function. Here’s an example using the small_table dataset (itself loaded using the load_dataset() function):
This table is a Polars DataFrame, but the preview() function works with any table supported by pointblank, including Pandas DataFrames and Ibis backend tables. Here’s an example using a DuckDB table handled by Ibis:
small_table_duckdb = pb.load_dataset("small_table", tbl_type="duckdb")
pb.preview(small_table_duckdb)DuckDBRows13Columns8 |
||||||||
The blue dividing line marks the end of the first n_head= rows and the start of the last n_tail= rows.
We can adjust the number of rows shown from the start and end of the table by setting the n_head= and n_tail= parameters. Let’s enlarge each of these to 10:
pb.preview(small_table_polars, n_head=10, n_tail=10)PolarsRows13Columns8 |
||||||||
In the above case, the entire dataset is shown since the sum of n_head= and n_tail= is greater than the number of rows in the table (which is 13).
The columns_subset= parameter can be used to show only specific columns in the table. You can provide a list of column names to make the selection. Let’s try that with the "game_revenue" dataset as a Pandas DataFrame:
game_revenue_pandas = pb.load_dataset("game_revenue", tbl_type="pandas")
pb.preview(game_revenue_pandas, columns_subset=["player_id", "item_name", "item_revenue"])PandasRows2,000Columns11 |
|||
Alternatively, we can use column selector functions like starts_with() and matches()` to select columns based on text or patterns:
pb.preview(game_revenue_pandas, n_head=2, n_tail=2, columns_subset=pb.starts_with("session"))PandasRows2,000Columns11 |
|||
Multiple column selector functions can be combined within col() using operators like | and &:
pb.preview(
game_revenue_pandas,
n_head=2,
n_tail=2,
columns_subset=pb.col(pb.starts_with("item") | pb.matches("player"))
)PandasRows2,000Columns11 |
||||
Working with CSV Files
The preview() function can directly accept CSV file paths, making it easy to preview data stored in CSV files without manual loading:
# Get a path to a CSV file from the package data
csv_path = pb.get_data_path("global_sales", "csv")
pb.preview(csv_path)PolarsRows50,000Columns20 |
||||||||||||||||||||
You can also use a Path object to specify the CSV file:
from pathlib import Path
csv_file = Path(pb.get_data_path("game_revenue", "csv"))
pb.preview(csv_file, n_head=3, n_tail=3)PolarsRows2,000Columns11 |
|||||||||||
Working with Parquet Files
The preview() function can directly accept Parquet files and datasets in various formats:
# Single Parquet file from package data
parquet_path = pb.get_data_path("nycflights", "parquet")
pb.preview(parquet_path)PolarsRows336,776Columns18 |
||||||||||||||||||
You can also use glob patterns and directories:
# Multiple Parquet files with glob patterns
pb.preview("data/sales_*.parquet")
# Directory containing Parquet files
pb.preview("parquet_data/")
# Partitioned Parquet dataset
pb.preview("sales_data/") # Auto-discovers partition columnsWorking with Database Connection Strings
The preview() function supports database connection strings for direct preview of database tables. Connection strings must specify a table using the ::table_name suffix:
# Get path to a DuckDB database file from package data
duckdb_path = pb.get_data_path("game_revenue", "duckdb")
pb.preview(f"duckdb:///{duckdb_path}::game_revenue")DuckDBRows2,000Columns11 |
|||||||||||
For comprehensive documentation on supported connection string formats, error handling, and installation requirements, see the connect_to_table() function.