frame-search 0.2.0

Query dataframes with GitHub search syntax

Frame Search

A GitHub search inspired interface to DataFrames.

Powered by narwhals.

Installation

Install from PyPI:

uv add frame-search

Usage

API

Importing frame_search adds a search properties to pandas and polars objects.

# Import to add `search` property to DataFrames
import frame_search  # noqa: F401

import polars as pl

df = pl.DataFrame({
    "name": ["Alice Smith", "Bob J. Dawkins", "Charlie Brown"],
    "age": [25, 30, 35],
    "hometown": ["New York", "New York", "Chicago"]
})

df.search('age:<30 hometown:"New York"')

shape: (1, 3)
┌─────────────┬─────┬──────────┐
│ name        ┆ age ┆ hometown │
│ ---         ┆ --- ┆ ---      │
│ str         ┆ i64 ┆ str      │
╞═════════════╪═════╪══════════╡
│ Alice Smith ┆ 25  ┆ New York │
└─────────────┴─────┴──────────┘

Interactive Search in Marimo Notebooks

Use with marimo to create a search interface for DataFrames:

import marimo as mo

search = mo.ui.text(label="DataFrame Search Query:")
search

Then use on a DataFrame:

import polars as pl

import frame_search  # noqa: F401

df = pl.DataFrame({
    "name": ["Alice Smith", "Bob J. Dawkins", "Charlie Brown"],
    "age": [25, 30, 35],
    "hometown": ["New York", "Los Angeles", "Chicago"]
})

df_filter = df.search(search.value)

df_filter

Here is another example in a Marimo notebook:

Search Syntax

The search syntax is inspired by GitHub's search syntax. Here are some resources:

• Cheatsheet
• GitHub Docs

Not all syntax features are currently supported. View the GitHub issues for planned features or to request new ones.