I've been using jq quite a bit lately and agree that the docs would benefit from more complex examples. However, I've been able to get some fairly complex solutions done with jq. Do you have a concrete example of something you are trying to do?
I have server logs in jsonlines format in a file. My goal is to display some basic information (URL, referrer, time stamp, IP address, and user agent) for each log line with a particular header set to a specific value. Headers are in $.request.headers and are an array of key-value pair arrays.
Figuring out this use case from the jq docs or jqplay has been a major struggle for me. I feel that this use case reflects 90% of what I would want to use jq for. I feel that if I can't get over this hump just from docs, there's no way I could justify bringing this tool on board with my team.
Sounds like you're after the select() filter, which evaluates a boolean expression and passes the input to the output only if the expression is true.
So your example would be something like: select(.request.headers|map(.[0] == "X-My-Header" and .[1] == "my target value")|any)|<pick out some keys to display>
I realise though that your point wasn't the specific example, it's that the docs for these kind of cases are poor, and you aren't wrong.
I guess my main advice is to not think of jq as something like cut or sort - instead, it's more like awk or sed. You can do lots of crazy things with sed, but it's not immediately obvious how just from reading the man page. These kinds of tools require a little more time investment but are very powerful.
