https://github.com/williambdean/frame-search
A GitHub search inspired interface to DataFrames
https://github.com/williambdean/frame-search
data-science dataframes github
Last synced: 4 months ago
JSON representation
A GitHub search inspired interface to DataFrames
- Host: GitHub
- URL: https://github.com/williambdean/frame-search
- Owner: williambdean
- Created: 2025-08-07T16:31:54.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-08-24T10:09:30.000Z (4 months ago)
- Last Synced: 2025-08-31T12:57:18.489Z (4 months ago)
- Topics: data-science, dataframes, github
- Language: Python
- Homepage:
- Size: 307 KB
- Stars: 4
- Watchers: 0
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Frame Search
[](https://github.com/astral-sh/ruff)
[](https://github.com/williambdean/frame-search/actions/workflows/tests.yml)
[](https://badge.fury.io/py/frame-search)
A GitHub search inspired interface to DataFrames.
Powered by [`narwhals`](https://narwhals-dev.github.io/narwhals/).
## Installation
Install from PyPI:
```terminal
uv add frame-search
```
## Usage
### API
Importing `frame_search` adds a `search` properties to pandas and polars objects.
```python
# 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"')
```
```text
shape: (1, 3)
┌─────────────┬─────┬──────────┐
│ name ┆ age ┆ hometown │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ str │
╞═════════════╪═════╪══════════╡
│ Alice Smith ┆ 25 ┆ New York │
└─────────────┴─────┴──────────┘
```
### Interactive Search in Marimo Notebooks
Use with [`marimo`](https://marimo.io/) to create a search interface for DataFrames:
```python
import marimo as mo
search = mo.ui.text(label="DataFrame Search Query:")
search
```
Then use on a DataFrame:
```python
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](https://gist.github.com/bonniss/4f0de4f599708c5268134225dda003e0)
- [GitHub Docs](https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax)
Not all syntax features are currently supported. View the [GitHub issues](https://github.com/williambdean/frame-search/issues) for planned features or to request new ones.