I think the definition of what full-text search means is clear. The way of expressing/writing it in the URL is what I wanted to discuss.

I meant either q=<text> XOR q=<fancy-query-parameters> but never both together.

I agree

The trick there is recognizing whether we have a full text search or a filter by analyzing the content, e.g. if there's an unescaped = in there, it's probably a filter.

If we don't want to have to escape operators in user input, I think we'd have to break the q parameter into search and filter, maybe.

It sounds like you're asking for the ability to extract a parameter from the q parameter, right? Why not just pass the additional parameter in like the fetch_sboms function you cite expects? What's the benefit of passing it in the q?

yes, the ability to extract and remove a parameter from q is what I'd like to see.

• Carlos: I'd like to query SBOM's labels as q=labels=label1|label2|label3&name=quarkus. It should be equivalent to query Advisories by vulnerability e.g. q=severity=high|medium|low. To me this is a valid query.
• Jim: q=labels=label1|label2|label3&name=quarkus is invalid, you need to use q=labels:app=something&labels:key=value because our labels internally are defined as a JSONB type.
• Carlos: The internal definition of a model/table should not limit the q definition.

Proposal:

• How to make q=labels=label1|label2|label3&name=quarkus work even though the internal db definition does not allow it?

let q=`q=labels=label1|label2|label3&name=quarkus`
let labels = q.extract("labels"); // labels='label1|label2|label3'
let new_q=q.delete("labels"); // new_q=name=quarkus
// let's parse the 'labels' string with any method we have in mind
let parsed_labed: Vec<Label> = parse(labels);
let output = fetch_sboms(new_q, parsed_labed);

Long story short:

• Allow a key being extracted and later removed from q
• Apply the current SQL mapping to the remaining q
• Allow manual parsing of fields that do not match the DB tables.

I think I am reconsidering my proposal xD. Would it make sense to define the label selector outside q? E.g. http://localhost:8080/api/v2/sbom?label_selector=some_text&q=another_text This would be similar to the kubernetes label selector rest api. If q has the limitation of "needs to match the db tables/columns", label_selector would not be limited by it as it is outside q, it will require manual translation into sql queries though.

• How to make q=labels=label1|label2|label3&name=quarkus work even though the internal db definition does not allow it?

We can make that work the way you expect. And I know you don't like the answer being determined by how the data is stored, but because it is stored as a map, we need to answer this question: what should happen when the values for those labels differ?

If we stored labels in an array -- no values, just "tags" -- the question would be moot, because the above query already works as you expect. But because they're in a map, we can just assume their values will be "". But they might not be. Should they still be returned? If the label1 value for one advisory is "foo" and "bar" for another one, should both be returned by your query?

If you say "yes", I think I can make that work.

I know you're tired of me asking, but what problem is this solving exactly? 😄

No worries, that is a valid question... I think the problem of q is that it does not expose exactly which filters I can use within q.
If we were to extract progressively whatever filter inside q outside it and make them first class citizens in the HTTP Query Parameters world, then all those fields will appear in Swagger UI and in the Openapi definition.

I think that is a big problem worth solving, even if the majority disagree :) .

Screenshot From 2025年06月04日 16-50-28

That's fair. And I agree it's a problem. There is an internal function that returns the valid fields, but it's not exposed in any structured way. At present, if you pass an invalid field in a filter, e.g. q=foo=bar, the error message will contain a list of the valid fields, but having them in the openapi definition would be an improvement.

And just to repeat, I meant to do it progressively, not necessarily today but move towards a more mature API. The current q can coexist with the new query parameters.

@jcrossley3 as everything works for the time being I forgot to follow up on this Discussion.
I feel like we (the team) could define regular meetings or populate regularly any ADR to see how to open the possibility of enhancing these things.

• List any current problem we might think of
• Solve a real a real problem if any

Would be nice to hold a beer and discuss about these things in good faith :)