Is there a getting started -like guide?

[YJDoc2]

Hello 👋 Thanks a lot for making this amazing project! This seems something really interesting .

I was wondering is there any getting started guide that would basically do a walkthrough for writing an adapter and using this to create complex, cross data-source queries ; similar to the hackernews - github -yaml example, but in a more tutorial style?

If that doesn't exist , I think it would be a great addition for beginners and interested people to get started with using this, and thinking of how this can be used for their own problems. One issue I'm facing with using this right now, even for a play-project ; is that because this is so new, and unlike anything else I have seen - multi data sources, with power to query from a single interface - it is hard for me to imagine exactly what I should use this for. This might be just a -me- problem, but I still think a tutorial like getting started guide would be a good addition if it doesn't exist yet.

Also is there any docs on the query language itself? I saw that it is supposed to be a subset of graphql, but having a single place to refer possible operators and filter and general syntax might be helpful for newcomers.

In case something like both above do not exist, would you be willing to accept PRs related to them/ discuss on how they should be done ( in repo itself, seprate mdbook, a single blog post somewhere or something else altogether)?

Thanks a lot!

[obi1kenobi]

The docs are currently minimal and woefully incomplete. I'd be thrilled to accept PRs to improve the README and crate doc-comments, and either add a docs directory to the repo or use Discussions here to post tutorials and getting started guides — not sure which would be better.

I think the problem you describe is very common, and very worth solving. I know this is a poor answer, but right now, the best source for learning the query language is going through the example queries in the playground (hackernews, Rust APIs), which cover nearly all of the language functionality.

If you're inclined to write some of the resources you described, I'd be thrilled to support you by answering questions, reading drafts, and anything else you'd need. This is a super ambitious project on which I'm stretched quite thin, so I'd greatly appreciate the help!

[YJDoc2]

Also a quick question -
I haven't looked at implementing an adapter yet apart from that it is a trait based thing ; but are trustfall adapters composable?

For example if someone has an adapter for github, and someone else has an adapter for yaml, can I add both packages as dependencies and then compose them, so I can write a single query which queries github raw files and then process ci yamls ? Not necessarily as simple as this, but essentially something like this. Or do we need to pipeline them manually, so I create query engine using one adapter, get its results, then create a new instance using second adapter and pipe the data from first into second and use two queries to get the final result?

Apologies for throwing a question without doing too much research 😓

[obi1kenobi]

Currently traveling, apologies for brevity. These are all reasonable
questions. Absolutely no need to apologize, it's on me for not making the
answers easier to find.

Adapters are designed to be composable, but I haven't yet published APIs
for that. It should be a fairly automatic process, but good APIs are hard.
Of course anyone could implement their own composition in the meantime.

Happy to include docs in the repo. Please feel free to act with agency in
designing and writing the docs -- you're in charge. I'm happy to merge PRs
and also happy to proofread, answer questions, or offer suggestions if
you'd like.

I'd recommend keeping the querying tutorial separate from the adapter
implementation tutorial, since the latter is specific to the programming
language (Rust, Python, JS/TS, etc.) while the query syntax is always the
same.

I also have some adapter autogeneration tools I plan to publish soon, which
should make adapter writing easier and should be part of those tutorials.

Thanks again! My schedule should be more back to normal in around a week or
so, and I hope to be able to help with docs and anything else you might
need.

[YJDoc2]

Hey, no problem!
Thanks for the response, I'll get working on the initial setup/basic guide as discussed. I'll figure out what would be a good example for a new user to write adapter, and get back to you when I have something ready and written 👍

[obi1kenobi]

Feel free to send drafts my way as well. It doesn't have to be fully ready. "A little feedback early is better than a lot of feedback later" and all that :)

[YJDoc2]

Hey, yep! I was a bit busy last few days, so couldn't update much. I'll definitely get the feedback on drafts as well, not just the "final" version :) I'll update here once I have something to show, thanks!