Query collection items based on fields value

[emilienbidet]

Hello KeyStatic core team !

I was wondering if the Keystatic reader API plan to integrate a way to query over the collection items.

See an example below :

const slugs = await reader.collections.post.findMany({
    where: {
       category: "culture",
    }
});

My use case is the following :
I want to create a blog with categories pages that contain posts filtered by categories.

If you think it could be integrated in the Keystatic vision. I would be glad to help develop this feature.

Thank you very much
Emilien

[simonswiss]

Hey!

If you mean just querying an entire collection, you can already do this with reader.collection.{collectionName}.all() or reader.collections.{collectionName}.list().

.all() will give you all the fields, while .list() will only give you an array of slugs.

Do you mean being able to pass a dynamic collection name (based on category)?

If so, I've handled a simple case like this in one of my projects with something like this (haven't tested the code I'm writing here):

const sessionsLookup = {
  'sydney': reader.collections.sydneySessions,
  'woopi': reader.collections.woopiSessions,
  'coffs': reader.collections.coffsSessions
}

const collection = sessionsLookup[region] // region is received a prop

const sessions = await collection.all()

I agree it would be nice to be able to pass the collection name dynamically.

[emilienbidet]

Hello Simon ! Thank you for your reply !

It's not about being able to pass a dynamic collection name.

It's about getting items that match filters, here is an example :

I have a list of hotels.
Retrieve all hotels with a price field lower than 100.

Like so :

const slugs = await reader.collections.hotels.findMany({
  where: {
    price: {
      lte: 100
    },
});

[simonswiss]

Oooh, gotcha.

Yeah, for now you need to get all the hotels, and then filter them out before passing the data to your frontend — but I agree that would be nice to be able to do some ORM-like query filtering.

[JedWatson]

At this stage, filtering content in the Reader API would involve loading all the files in the collection anyway, since we're not using a database. That's fine for smaller collections, but we're a bit wary of adding something that looks like it should "just work" and then someone uses it on a collection with a few thousand items in it and ... it's not going to scale well.

Also, designing a filter syntax is a fair bit of surface area to document and maintain (I mean there are several we could copy, like Prisma's or most other ORMs, but it would still be custom) and we're trying to keep things lighter right now so we can focus on things that are hard to do in user land.

If you've got a collection where the scale / performance isn't going to be a problem, then it's pretty easy to do yourself:

const allHotels = await reader.collections.hotels.all();
const cheapHotels = allHotels.filter(I => i.price <= 100);

There may even be data filtering libraries on npm that give you a more expressive syntax for this, or optimise the process in various ways? If you wanted something like this in your site to be queried from the codebase at runtime you could (for example) throw it in redis or sqlite, or even an optimised in-memory data structure.

So I'm not sure this is something we should actually try and solve in Keystatic itself, it feels like more of a separate / generic problem space. (that's not a hard line, just sharing current thinking)

Also, while we could probably cover a range of common requirements (gt / gte / contains / equals / startsWith plus case-insensitive variants, etc) you get to more complex requirements like OR / AND statements, etc. We've been down that rabbit hole with Keystone and it goes deep.

Honestly, I actually think the flexibility of just writing whatever comparison logic you want in a filter function is easier; you don't have to learn any custom API syntax, it's Just JavaScript.

Definitely, we should at least add some examples to the Reader docs for anyone else looking for this functionality. @emilienbidet if you're interested in contributing, that would be an awesome start!