Documentation Guide - Querying / Filtering

[hobofan]

Problem Description

Re: Better Documentation #853 Querying

What are you trying to accomplish?

• Create an entry-level guide/reference on how to do the most common querying tasks. The ActiveRecord querying guide is a good example for that (though this guide obviously won't be on the same level for a long time).
• The guide will be focused on "If you want to do this you have to do this" and will not go into too much depth on the traits behind the functionality and how to obtain them, as that will be covered by other guides (Documentation - Model Annotation / Traits #1107)

Checklist

• I have already looked over the issue tracker for similar issues.

[bovee]

A guide would be great, but even a table of SQL <-> Diesel would be super helpful. For example, I had difficulty finding out how to emit IN query statements without grepping the source (I think it's column.eq_any()?) and a list of column methods would have been incredibly useful.

[notryanb]

@hobofan - Just checking in to see if you're still working on this issue (or need help?). I think it is still a good idea and would be helpful with the 1.0 release just around the corner.

[hobofan]

@notryanb Sorry, I got tied up in a fulltime freelancing contract the last two months. I'll be free again beginning next week, and this is one of the first things I'll work on!

[hobofan]

I'm so sorry everyone that I was holding up this important part of the documentation for so long. I'm sadly constantly finding myself busy with other stuff and also haven't used Diesel since writing my last comment here, so I don't think I can write the documentation at the level it deserves.

It's probably best if someone else who is using this project more takes on this issue.

[hbobenicio]

I miss guides and docs about queries too.
There is a "All About Updates" guide. There is also a "All About Inserts" guide. But no "All About Queries"... :(
In my case (newcomer here) I'm struggling to make dynamic queries (for a paginated listing use case).
Mining help and basic usage directly from docs.diesel.rs is kind of cumbersome...

[dessalines]

This really needs to be on both the homepage and getting started. There are no references to table::filter , the .gt or .eq commands... I know how to update and insert but no idea how to query data.

[dessalines]

I found a good page from the docs: even just linking to this from the getting started page would help a lot:

https://docs.diesel.rs/diesel/query_dsl/trait.QueryDsl.html

[jimmycuadra]

This is desperately needed. It's really difficult to figure how to do do any sort of querying with Diesel.

[matteosister]

I find it really hard to understand how to reuse pieces of queries. The Extending Diesel guide focus on solving one particular problem. And does it in a hard to understand way. And it also seems outdated, for example the sql_function! that is used there is deprecated.

I would like to see some guides on how to turn a type into a query piece. How to reuse the same type on many columns, without rewriting it for every column. How to structure my code and write types to use them with the diesel type system.

These are the main problems for me right now. So big thumb up for a guide like this...even if this issue is from nearly 3 years ago 😢

[weiznich]

@matteosister I agree with you that this guides are (partially) missing and should be written. That brings me to the problem why they are not written yet: None of the current diesel maintainers had the bandwidth to do that. We all have a live to life beside diesel, so we only have a limited amount of time available to work on stuff. Additionally we are using diesel in our own projects. The result of that is that we prioritize stuff that's important for those projects. As hard as it sounds, but from that point of view documentation is nice, but not as useful as a specific feature I need by myself.
All of that does not mean there should be no written guide on that, just that someone needs to step up and write such an guide.

Now for the concrete questions:

The Extending Diesel guide focus on solving one particular problem. And does it in a hard to understand way.

I would like to disagree here. This guide shows 3 ways how to extend diesel. Each of them is quite exemplary for it's use case.

And does it in a hard to understand way.

Please elaborate which part you fund hard to understand.

And it also seems outdated, for example the sql_function! that is used there is deprecated.

I agree that the old syntax there should probably be fixed, otherwise this code continues to compile. Additionally the documentation of sql_function! has quite extensive documentation on allowed variants.

I would like to see some guides on how to turn a type into a query piece. How to reuse the same type on many columns, without rewriting it for every column. How to structure my code and write types to use them with the diesel type system.

That's basically part 2 (or 3) of the guide, how to write a custom query node and define custom operators. The general idea is the same. As this requires quite complex generic code I doubt that this will ever be part of same small good understandable official guide. It depends a bit how far you want to go, but in the end you need some good understanding about the rust trait system in general and how that is utilized by diesel. (There is an talk by Sean at rustconf and a workshop given by me at rustfest available, that contains some information on this topic.)

Beside of that I can only offer to answer specific questions in our gitter channel or in our forum. You should be familiar with the details of rusts trait system, otherwise it will be quite hard. (This issue is not the right place to discuss concrete use cases).

[matteosister]

I didn't want in any way push anybody doing something. I know how hard it could be to be part of an open source project while using it at work.

I used rust at work for a year now, I'm not an expert in any way. Still I wanted to share (without blaming) how hard it could be to approach this great library, and the frustration of not being able of doing things that seems simple in other languages (coming from elixir and ecto).

So don't take it personally. I'll be glad to help if I could...