# fsql: Query Your Filesystem with SQL-Like Syntax

> fsql is a Go command-line tool that runs SQL-style SELECT queries against the local filesystem, letting you filter files by name, size, modification time, hash, and mode. It supports subqueries, glob patterns, environment variables in source paths, and attribute modifiers for formatting output.

**kashav/fsql** — Search for files using a fun query language

- Repository: https://github.com/kashav/fsql
- Stars: 3,988 · Forks: 117
- Language: Go
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/kashav-fsql

## What fsql Does and Who It Serves

fsql translates SQL-style SELECT queries into filesystem walks. Engineers who already work in SQL can use familiar syntax to find files instead of memorizing `find` flags. A query like `SELECT name, size FROM ~/Desktop WHERE size > 1000000` finds all files under ~/Desktop larger than one megabyte and shows their names and sizes.

The tool targets developers and system administrators who need to locate files by combinations of attributes that would be unwieldy as find expressions. It is not a database and does not index the filesystem; it walks the specified source paths at query time.

## Query Syntax: SELECT, FROM, WHERE

Every query has three optional clauses. SELECT names the attributes to display. FROM names the source directories. WHERE specifies conditions.

Attributes available for SELECT and WHERE are `name`, `size`, `time`, `hash`, and `mode`. Using `all` or `*` selects all attributes. If SELECT is omitted entirely, all attributes are shown.

The FROM clause accepts relative paths, absolute paths, environment variables (`$GOPATH`), and tildes (`~`). Prepending a hyphen to a source path excludes it from the walk. Glob patterns are supported in source paths. A hyphen-prefixed directory that happens to start with a hyphen can be included by writing `./-foo` instead.

The WHERE clause joins conditions with AND and OR. Precedence is left-to-right in order of appearance, so `WHERE a AND b OR c` is not the same as `WHERE c OR b AND a`. Parentheses override this ordering. Negation uses the NOT keyword preceding the condition. Negating a parenthesized group is not supported; apply De Morgan's laws to rewrite the condition.

## Installing fsql

Three installation paths are available. Via Homebrew on macOS:

```bash
brew install fsql
```

Via the Go toolchain:

```bash
go get -u -v github.com/kashav/fsql/...
```

This installs the binary to `$GOPATH/bin/fsql`. From source:

```bash
git clone https://github.com/kashav/fsql.git $GOPATH/src/github.com/kashav/fsql
make
```

The `make` target builds the binary in the repository directory. Pre-built binaries for specific platforms are available from the GitHub releases page; the latest tagged release is v0.5.2 from 2023-11-08.

## Operators, Conditions, and Attribute Modifiers

Each attribute supports a specific set of operators. For `name`: equality (`=`), inequality (`<>` or `!=`), list inclusion (`IN`), simple pattern matching (`LIKE` with `%` wildcards), and regular expression matching (`RLIKE`). For `size` and `time`: all algebraic comparisons (`>`, `>=`, `<`, `<=`, `=`, `<>` or `!=`). For `hash`: equality or inequality only. For `mode`: `IS REG` for regular files and `IS DIR` for directories.

Attribute modifiers transform how values are read or displayed. For `size`, `FORMAT(size, MB)` converts bytes to megabytes. For `time`, `FORMAT(time, ISO)` formats timestamps as ISO 8601. Custom time layouts follow Go's reference time format: `Mon Jan 2 15:04:05 -0700 MST 2006`. For `name`, `UPPER` and `LOWER` convert case; `FULLPATH` and `SHORTPATH` control path display. For `hash`, `SHA1(hash, n)` computes a SHA1 hash and shows the first n characters.

Modifiers can appear in both SELECT and WHERE clauses, though `FULLPATH` and `SHORTPATH` are available only in SELECT.

## Subqueries and Their Constraints

fsql supports subqueries for building conditions from the results of another query. A subquery is a complete fsql query embedded in a WHERE clause condition. The outer query tests whether a file attribute matches any value returned by the subquery.

The README documents one constraint: selecting multiple attributes in a subquery is not supported. If more than one attribute or `all` is specified in the subquery SELECT, only the first attribute is used. Cross-referencing the outer query from within the subquery (what SQL calls a correlated subquery) is not yet implemented; the README links to issue #4 for those who want to contribute.

Precedence in compound WHERE conditions applies to subquery results the same way it applies to literal conditions.

## Limitations and Cases Where fsql Falls Short

fsql walks the filesystem at query time with no index. On large directory trees, queries that touch many files will be slow. There is no caching or persistent index.

The query language does not support JOIN, GROUP BY, HAVING, or aggregate functions like COUNT or SUM. Set-based operations require multiple fsql invocations combined with shell tools.

When passing queries via stdin without quotes, reserved characters such as `*`, `<`, and `>` must be escaped to prevent the shell from expanding or redirecting them. Interactive mode is available for repeated queries, but the README does not document its full feature set.

The default `size` unit is bytes and the default `time` format is `MMM DD YYYY HH MM`. Both must be explicitly overridden with FORMAT modifiers if a different representation is needed.

## fsql Versus GNU find and fd

The closest standard alternative is `find`, a POSIX utility available on every Unix system. The difference is ergonomic: `find` uses its own flag-based syntax for conditions (`-name`, `-size`, `-mtime`, `-newer`), while fsql uses SQL's WHERE clause syntax with named operators. For users comfortable with SQL, fsql reads more directly; for users comfortable with `find`, there is no installation required.

A more modern alternative is `fd`, a fast, user-friendly find replacement written in Rust. fd focuses on name-based search with regex support and does not expose a SQL-style query language or attribute comparison operators like size ranges or hash matching. fsql's ability to filter by hash, compare sizes numerically, and compose conditions with AND/OR and subqueries gives it capabilities fd does not expose.

fsql requires Go 1.21 or later, as declared in go.mod.

## Conclusion

fsql is a good fit for developers who think in SQL and want to filter files by name, size, time, or hash from the command line without constructing complex find expressions. The latest release is v0.5.2 from 2023-11-08, but the last push to the repository was on 2026-07-25, indicating continued maintenance without a formal release. The query engine lacks JOIN and GROUP BY, so set-based operations across directories require subqueries or external tooling. Before using fsql with glob patterns on large directory trees, check that the shell escaping for glob characters is correct, since unescaped `*` expands in the shell before fsql receives it.

## FAQ

### How do I install fsql on macOS?

Run `brew install fsql` to install from Homebrew. Alternatively, use `go get -u -v github.com/kashav/fsql/...` if the Go toolchain is installed, which places the binary at $GOPATH/bin/fsql.

### What attributes can I query with fsql?

fsql supports name, size, time, hash, and mode. Name supports equality, LIKE, and RLIKE. Size and time support numeric comparisons. Hash supports equality and SHA1 truncation. Mode supports IS REG and IS DIR.

### Does fsql support regular expressions in WHERE clauses?

Yes. The RLIKE operator on the name attribute accepts a regular expression pattern. The LIKE operator supports simple wildcard matching with % for zero or more characters.

## Sources

- [Issues](https://github.com/kashav/fsql/issues)
- [kashav/fsql on GitHub](https://github.com/kashav/fsql)
- [License: MIT](https://github.com/kashav/fsql/blob/master/LICENSE)
- [README](https://github.com/kashav/fsql/blob/master/README.md)
- [Releases](https://github.com/kashav/fsql/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kashav-fsql