Is there intermediate documentation that is somewhere between the beginner's tutorial and the API reference page?

[chrispy-snps]

While working on the code described in #9757, I found it difficult to discover the following:

• The & and | are Ibis equivalents to and and or for expressions.
• JSONColumn results need to be cast to array<sometype> before chaining subsequent methods.

I eventually figured these out by reading Stack Overflow posts and Ibis repository issues. After figuring them out, I went back to the documentation to see where I should have learned this stuff. But I couldn't seem to find it.

The beginner's tutorial gives an overview of what Ibis is capable of. And the examples repository and API reference pages linked across the top of the Ibis homepage are great resources for developers actively using Ibis.

But where should a beginner go next after reading the tutorial? For example,

• How are Ibis expressions constructed, what are the most common operators, and what are the major object class building blocks?
• What is the syntax for querying inside JSON fields, and how does it differ from the syntax for querying native fields?

Hopefully it's not linked somewhere from the home page and I just didn't RTFM hard enough...

[gforsyth]

Hey @chrispy-snps -- I don't think you're missing anything, we don't have a broad intermediate tutorial available.

It seems like most of the questions you posed above revolve around JSON, where we could definitely improve our reference documentation. Are there other specific things you went looking for and had trouble finding? What sort of work are you doing? What did you try and what worked and didn't work?

[dschneiderch]

I would also be hugely in favor of some intermediate docs.
The examples in the Reference section are pretty barebones. Userbase seems to be pretty small so its hard to find examples. Overall this is an amazing library (coming from a guy with lots of dataframe experience but working in bigquery regularly)

[chrispy-snps]

@gforsyth - thanks for the reply!

For me, what would be helpful is some kind of introduction to the object types, operators, and methods that helps build my mental model for the machinery. Perhaps this could be done within the tutorial framework. For example, a tutorial focused on datatypes and the operators that can process them? Perhaps a tutorial specific to working with JSON data?

Thinking out loud, it would also be useful to have links from the tutorial to relevant reference topics. Perhaps visiting the reference docs from the context of "doing something" in the tutorial docs would help bridge the two domains together.