Show HN: FilterQL – A tiny query language for filtering structured data (opens in new tab)

(github.com)

77 pointsgenshii7mo ago21 comments

Hey all, I just released v2.0.0 of FilterQL, a query language and TypeScript library. This version adds support for Operations, which allow you to transform the data after filtering.

If you think this would be useful in a project you're working on, give it a try and let me know what you think!

21 comments

arnley7mo ago

We wrote something quite similar for Bouygues Telecom and based it on an ANTLR grammar [2].

It offers nested filtering out of the box. All feature-packed in a lightweight package.

[1]: https://github.com/bouyguestelecom/spl [2]: https://github.com/BouyguesTelecom/SPL/blob/main/src/antlr/S...

9dev7mo ago

This looks excellent. It’s just missing some documentation on usage, otherwise, I’d actually have an immediate use case for it!

LtdJorge7mo ago

The README is so good; visual demonstration, documentation, examples, proper Markdown formatting.. Love it.

genshiiOP7mo ago

Thanks! Glad my efforts there didn't go unnoticed :)

sandreas7mo ago

I'm always asking myself, why there is no language-independent standard for this to translate into SQL / LIST querying or processing and why this is almost never done in a kind of lisp-ish style to have a fast, compact, simple and easy parser...

  (OR 
    (IN id (list 1 2 3)) 
    (LTE createDate "2025-08-27")
  )

which would translate into

  WHERE id IN (1,2,3) OR createDate <= '2025-08-27'

dv_dt6mo ago

After I read the prql docs, i finally understood why sql was so often painful for me to write

drinkcocacola7mo ago

I see a mismatch between the library API `filter` vs the supported operator `| SORT rating desc"`. You could use the API to your advantage by separating concerns: add a new `.sort("fieldName")` method.

``` const recentGoodMovies = filterql .filter(movies, "year >= 2008") .sort("rating") .desc()

```

If adding helper methods for semantics and clarity is not the intent of the library, then I'd rename the `filter` method since it doesn't communicate the intention clearly.

The function executes a full pipeline filter expression + `|` operations like `SORT` and `LIMIT` (not just a predicate filter). So for instance naming it to `query` will match your README terminology and grammar (`query := filter | operation*`)

genshiiOP7mo ago

Hmm, maybe I need to think about this more, but since operations are a language feature (and could have any name, see custom operations), I don't think they could be attached to the filterql class like that.

You're right though, the naming of the `filter` method is confusing. I need to split off the filtering and applying of operations into two separate methods. And probably provide an additional `query` method like you said which would do what `filter` is doing now. Appreciate the feedback!

gritzko7mo ago

I myself made a simple query language out of necessity. My key-value CRDT store [1] needed some syntax for basic queries. It was strictly minimalistic, like {type:fruit} would produce [{type:fruit name:banana}...] and so on. When I think how to evolve it I lean towards adding lisp-like expression support. Cause I have a small lisp readily available.

I wonder if there is a good birds-eye FAQ/HOWTO/overview of all the existing (families) of query languages. Just to systematize Datalog, GraphQL, SQL, there are tons of them.

[1]: https://github.com/gritzko/go-rdx

nnnnico7mo ago

I recently experimented with something like this and ended up going with MongoDB style queries (and field:operator:value syntax for a CLI wrapper)[1] as they are very powerful for nested/array operations and easy to parse everywhere but WAY more verbose than the syntax you chose for filterql! which also seems easy to understand for less technical folks. Love the project, do you plan on supporting nested values?

[1]: https://github.com/nicolaspasqualis/go-fq

freakynit7mo ago

I too went with MongoDb style when I implemented something like this:

1. Javascript: https://github.com/freakynit/Verdict

2. Java: https://github.com/freakynit/Verdict-java

MoyoGeorge7mo ago

Any plans on this supporting JSONSchema? Seeing as most/all popular TypeScript validation libraries, which will likely be used to define the shape of the data, support converting to JSONSchema now?

genshiiOP7mo ago

Ah good idea, thanks. Gonna put that on the todo list :)

cdaringe7mo ago

I like it! It’s nice offering a little DSL in various spaces. Curious where you’re plugging it in?

Any intended support for collections/sets? In JQL is do ‘“foo” not in (“evil”, “silly”)’ or similar matchers over sets, like if tags are on a ticket or if tickets an in an N states

genshiiOP7mo ago

I've been using it in a CLI tool [1] to query media in my *arr services.

If you're talking about a query where you want "foo" to not be "evil" OR "silly", you could write 'foo != evil || foo != silly'.

There's a separate case where the value itself is an array/collection/set, in which case doing anything with that is currently unsupported. Values can only be strings, numbers, or booleans.

[1] https://github.com/adamhl8/inspectarr

olivergregory7mo ago

It seems nice. However is there any way to query arrays within the datastructure itself? Or go deeper in the hierarchy, such as "model.cost"?

genshiiOP7mo ago

I thought about doing exactly what you suggested, where a query could access deeper properties with a syntax like "model.cost", but ultimately decided against it because I didn't like the complexity that would necessitate.

As for arrays, I usually opt for joining the string and then doing an "includes" query. e.g. ["sm", "md", "lg"] -> "sm,md,lg" and then you could write a query like "size *= md". Obviously this approach has its disadvantages though.

I'm definitely open to rethinking both of these if that's a common enough want/need.

h1fra7mo ago

why a dsl when you could do ql.filter<Movies>(movies).where('y', '>=', 2008) or even just use kysely with a plugin

genshiiOP7mo ago

Mainly because you might not always want to filter in-code. e.g. A CLI tool could take in a query as an argument, or a web app could allow a user to enter a query.

esafak7mo ago

If you're in the CLI I'd use nushell or dasel, if you're stuck with a legacy shell.

silicon_laser7mo ago

is there some thing like this in python?

j / k navigate · click thread line to collapse

21 comments

arnley7mo ago

We wrote something quite similar for Bouygues Telecom and based it on an ANTLR grammar [2].

It offers nested filtering out of the box. All feature-packed in a lightweight package.

[1]: https://github.com/bouyguestelecom/spl [2]: https://github.com/BouyguesTelecom/SPL/blob/main/src/antlr/S...

9dev7mo ago

This looks excellent. It’s just missing some documentation on usage, otherwise, I’d actually have an immediate use case for it!

LtdJorge7mo ago

The README is so good; visual demonstration, documentation, examples, proper Markdown formatting.. Love it.

genshiiOP7mo ago

Thanks! Glad my efforts there didn't go unnoticed :)

sandreas7mo ago

  (OR 
    (IN id (list 1 2 3)) 
    (LTE createDate "2025-08-27")
  )

which would translate into

  WHERE id IN (1,2,3) OR createDate <= '2025-08-27'

dv_dt6mo ago

After I read the prql docs, i finally understood why sql was so often painful for me to write

drinkcocacola7mo ago

``` const recentGoodMovies = filterql .filter(movies, "year >= 2008") .sort("rating") .desc()

```

If adding helper methods for semantics and clarity is not the intent of the library, then I'd rename the `filter` method since it doesn't communicate the intention clearly.

genshiiOP7mo ago

gritzko7mo ago

I wonder if there is a good birds-eye FAQ/HOWTO/overview of all the existing (families) of query languages. Just to systematize Datalog, GraphQL, SQL, there are tons of them.

[1]: https://github.com/gritzko/go-rdx

nnnnico7mo ago

[1]: https://github.com/nicolaspasqualis/go-fq

freakynit7mo ago

I too went with MongoDb style when I implemented something like this:

1. Javascript: https://github.com/freakynit/Verdict

2. Java: https://github.com/freakynit/Verdict-java

MoyoGeorge7mo ago

Any plans on this supporting JSONSchema? Seeing as most/all popular TypeScript validation libraries, which will likely be used to define the shape of the data, support converting to JSONSchema now?

genshiiOP7mo ago

Ah good idea, thanks. Gonna put that on the todo list :)

cdaringe7mo ago

I like it! It’s nice offering a little DSL in various spaces. Curious where you’re plugging it in?

Any intended support for collections/sets? In JQL is do ‘“foo” not in (“evil”, “silly”)’ or similar matchers over sets, like if tags are on a ticket or if tickets an in an N states

genshiiOP7mo ago

I've been using it in a CLI tool [1] to query media in my *arr services.

If you're talking about a query where you want "foo" to not be "evil" OR "silly", you could write 'foo != evil || foo != silly'.

There's a separate case where the value itself is an array/collection/set, in which case doing anything with that is currently unsupported. Values can only be strings, numbers, or booleans.

[1] https://github.com/adamhl8/inspectarr

olivergregory7mo ago

It seems nice. However is there any way to query arrays within the datastructure itself? Or go deeper in the hierarchy, such as "model.cost"?

genshiiOP7mo ago

I'm definitely open to rethinking both of these if that's a common enough want/need.

h1fra7mo ago

why a dsl when you could do ql.filter<Movies>(movies).where('y', '>=', 2008) or even just use kysely with a plugin

genshiiOP7mo ago

Mainly because you might not always want to filter in-code. e.g. A CLI tool could take in a query as an argument, or a web app could allow a user to enter a query.

esafak7mo ago

If you're in the CLI I'd use nushell or dasel, if you're stuck with a legacy shell.

silicon_laser7mo ago

is there some thing like this in python?

j / k navigate · click thread line to collapse