Wp-graphql: Query schema for orderby inside where is not intuitive

[saarnilauri]

Currently the orderby is set like this:

query GET_POSTS {
        posts (
            where: {
                status: PUBLISH
                orderby: { field: TITLE, order: ASC }
            }
        ) {
            edges {
                node {
                    title
                }
            }
        }
    }

To me this is not intuitive as orderby is not really part of where clause. To me it would make more sense to set it as follows:

query GET_POSTS {
        posts (
            where: {
                status: PUBLISH
            }
            orderby: { field: TITLE, order: ASC }
        ) {
            edges {
                node {
                    title
                }
            }
        }
    }

I know this will break all queries using orderby so, might be a big breaking change for many developers.

Please, let me know your thoughts.

[jasonbahl]

@saarnilauri I would agree.

I plan to revamp connection args altogether in the somewhat near future.

Still needs some discussion, but the connection args are generally pretty ugly, in my opinion. . .

Initial implementation tried too hard to just mirror WP_Query capabilities, without thinking through how to improve the experience.

[jasonbahl]

Some other things that bug me are that we have where args such as tagIn and categoryIn are hard coded into the connection args, even if the post type doesn't have categories and tags. . .and custom Taxonomies don't show.

It's a good time to revisit the connection args altogether

[drewbaker]

I would second that orderby has issues. It doesn't work at all when doing a meta query for example.

We use a custom meta field called developer_id to fetch specific pages (this is locked, so the client can never change it like they could with the slug).

A common use of this is to get all the child pages of the home page, to build out a grid of featured work. It impossible to get the order to change.

query GET_FRONT_PAGE_DATA($devId: String) {
    pages(
        where: {
            metaQuery: {
                metaArray: [
                    { key: "developer_id", value: $devId, compare: EQUAL_TO }
                ]
            }
            orderby: { field: MENU_ORDER, order: DESC } 
        }
        first: 1
    ) {
        edges {
            node {
                childPages {
                    nodes {
                        title
                        content
                        childPages {
                            nodes {
                                title
                                featuredImage {
                                    ...featuredAttachment
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

[hybridwebdev]

Hi, I'm also using your system as a framework I'm building so you'll probably end up seeing me a lot here from now on. I want to stay on topic for the thread, so I'll keep my input to it specifically.

As a whole, I believe that your current handling of the entire posts concept is a little...er...wonky. First and foremost, as mentioned above, stuffing syntax like orderby in it's own object is counter intuitive. In fact, your entire post query interface itself is to be quite frank...bad.

I don't understand why you've remapped standard query params such as notIn when in wp_query it's post__not_in. To me, the post object query interface should have a 1 to 1 relation directly with wp_query fields. To me it doesn't make sense to re-map these keys and I believe this is something I strongly believe needs to be fixed.

Additionally, while I can see SOME logic behind why each custom post type has it's own query interface, it does cause quite a bit of pollution in the Schema, compounded by the fact that your interfaces for each(post, posts, postsBy) are not grouped together in the schema documentation. Additionally, to me it just doesn't make sense to have 3 different interfaces for what is effectively the same thing. Why not just make a simple interface where you can do something like:

{
    wp_query( $params){

    }
}

And then be able to pass in params via a variable object.

I'm still in the process of learning the structure of your plugin, and like I said will likely try and contribute what I can in terms of either feedback or code, but I strongly feel that in order for the project to mature, you need to look at a restructuring of both your naming conventions (notIn vs post__not_in etc) to a structure that correlates with wp's convention. This will make it much simpler for the average WP dev to pickup, as they will simply need to learn gql syntax, and then immediately start utilizing your system without having to study the naming/mapping conventions.

[jasonbahl]

The goal of GraphQL isn’t to simply bring WPQuery to the client. It’s treating WordPress data as a Graph.

I agree that the args for connections are funky, but more closely mirroring WP_Query is further from the goal of treating WordPress content as an application data graph.

The args will be changing, but not to be closer to WP_Query, but further from it.

Terms like post__not_in only makes sense to an experienced WP developer, not a an application developer that’s never touched PHP.

The goal here is to have a declarative Schema that represents the Types of data in your application and the capabilities for interacting with those Types. Trying to query for a list of Cars using post__not_in doesn’t make sense unless you’re a seasoned WP dev, and that’s not/shouldn’t be a prerequisite here.

Often times folks working with consuming GraphQL have little or no knowledge of the underlying server technology.

Go look at the GitHub GraphQL API for example, and you won’t be able to discover any server implementation details from their Schema. The Schema describes the Types in the system and how to interact with the Types, it doesn’t mirror how their server is structured, and that’s a good thing. That allows them to change how their server resolves data without affecting their API. They could be on MongoDB today and Sequel tomorrow and the GraphQL consumer wouldn’t know the difference.

Mirroring WP_Query on the client is far from the goal here.

You’re definitely welcome to filter in fields and arguments that make it feel more like WP_Query on the client for your use cases, but that’s not the direction we’re heading.

We’re working on bringing best practices from the greater GraphQL ecosystem to WordPress.

I appreciate the feedback, and I definitely think there’s still a LOT of work to do with the Schema.

I would recommend studying up a bit on GraphQL best practices before coming in and telling us our implementation is bad. It’s not perfect for sure, but just because it’s not familiar to you yet doesn’t mean it’s bad.

I look forward to seeing what you build with WPGraphQL. I think your feedback will help shape the project and hopefully my feedback can contribute to shaping how you think about WordPress as a Graph. 😀

[hybridwebdev]

To be honest, with the posts query essentially being an abstraction over wp_query, i strongly believe it's interface should be a 1 to 1 correlation for these reasons specifically:

1. As you said it allows a seasoned WP dev with backend knowledge to instantly use once they learn GQL syntax.

2. For those with no knowledge of the actual WP backend, they can still utilize the API and just ascertain interface syntax via GQL schema documentation. Additionally, if your schema documentation doesn't provide them enough info, they can easily consult WP's codex to figure out what the syntax they are using actually does behind the scenes. Sure they may think something like post__not_in is weird, but they'll still understand what it does as the documentation provides that info. If you think about it, post__not_in is far less ambiguous than notIn as it implies what it means. Whereas notIn could mean anything. Not in title, not in id, not in post type etc etc. A good syntax name can be self documenting which is one of the reasons why WP chose the conventions they did.

3. Portability. I'm Joe blow dev. I wanna convert my existing system to one that uses your GQL framework. Lucky for me you've provided a handy function that allows me to make gql queries even in the backend. Yay for me as this makes life a bit easier. But oh wait, i can't just change a few things and have it intergrated. Nope, I have to look at each of my wp_querys and change them so their syntax uses your convention. Well, there goes several hours of my life changing, testing and making absolute sure that the syntax is exactly right.

4. It makes it easier for backend devs to extend. I myself am a seasoned WP professional, having worked with it since all the way back to 2.x. I've done pretty much everything you can thing of. Custom api integration. WC product management integrations with third party api systems. You name it, I've probably done it. Having said that, i initially found your system hard to get going with, specifically because of things like id mapping to what seems to be a hashed key, rather than a typical post->ID. This caused me to have to do a lot of additional digging just to figure out how to get the data I wanted.

I understand that your goal is to simplify the front-end, and that's great. However, you also have to think of the developers that want to extend your system. By providing a 1 to 1 correlation to WP's conventions, you're not only making the front end easier to utilize, you're also making it easier for back-end devs to extend which, again, is another way that your project will mature.

As for schema changes, I think that's a moot point as this is a wrapper over WP. WP's not going to be changing wp_query in a way that'd break you using their syntax. As wp devs we all know this to be true. As the wp dev community has come to depend on a certain structure, it's counter-productive to just "re-invent the wheel" so to speak by throwing out that convention and re-defining your own.

TLDR: More than just front end devs want you use your system. There's no reason to throw a solid syntax/structure and all the documentation/Stackoverflow Q/A that has been built over several years, "just because".

[jasonbahl]

You’re welcome to filter in fields that mirror WordPress or use a competing implementation that provides a Schema shape like you’re suggesting.

The core of this project is not going in that direction though.

GraphQL is WAY bigger than WordPress, and this project is working toward bringing the GraphQL best practices to WordPress, not the other way around.

I’d suggest checking out graphql-wp, as they follow the approach you’re suggesting.

https://github.com/tim-field/graphql-wp

I think if you use that implementation often you’ll likely come across pain points and maybe come to appreciate some things we’ve done in our approach.

Maybe you won’t and instead find their approach works better, and that’s great too.

[jasonbahl]

Also, fwiw, based on your last comment...the first use of the plugin was for server->server communication, not front end.

I work at a newspaper and we had serious problems with syndicating content over the WP REST API. WPGraphQL was born to solve server->server issues. GraphQL at large is used more for JS applications and we try to support that, but the biggest use case, that I’m aware of to date, is our internal PHP->PHP implantation.

We now communicate server to server using WPGraphQL and it has alleviated many of our pain points.

[hybridwebdev]

You’re welcome to filter in fields that mirror WordPress or use a competing implementation that provides a Schema shape like you’re suggesting.

The core of this project is not going in that direction though.

GraphQL is WAY bigger than WordPress, and this project is working toward bringing the GraphQL best practices to WordPress, not the other way around.

I’d suggest checking out graphql-wp, as they follow the approach you’re suggesting.

https://github.com/tim-field/graphql-wp

I think if you use that implementation often you’ll likely come across pain points and maybe come to appreciate some things we’ve done in our approach.

Maybe you won’t and instead find their approach works better, and that’s great too.

I feel like you might be getting a bit defensive here. I'm merely trying to provide constructive and helpful feedback. I like your project and in no way am meaning to undermine what you're doing or how you've done it. I'm merely trying to provide suggestions on how to improve it overall.

At the end of the day, this is built for WP. Trying to tell WP how they, and their entire community "should be doing things" isn't going to be received well. You're essentially telling them what they've done is "bad" and that your way is better. That negates their entire codebase, the documentation that goes with it, the countless SO questions etc. For example https://stackoverflow.com/questions/40850559/wp-query-post-not-in-not-working

Take a look at the answer and you'll see what I mean. That person was able to answer the question because WP_QUERY is well documented and countless devs like us can use it without even having to look at the documentation.

Now in with your syntax, that answer is irrelevant as it doesn't correlate with your syntax. This is a HUGE sticking point, as you're throwing out all the convention...this comprehensive knowledge that exists through the internet and the entire WP community, just because you think "your way is better". I'm sorry to say, and I mean no disrespect, but if you think you can redefine wp's conventions and they'll just adopt...well that will NEVER ever happen. Instead of expecting people to adopt to your syntax and re-learn how to do things, why not simply adopt the conventions that have been battle tested.

Also, I took a look at the git repo you linked, and while I like what I see, it's clearly abandoned and no where near production ready.

Can i merely suggest that, maybe you get more feedback from the WP community in general, and see what they have to say about the conventions used here.

[drewbaker]

As someone that has built a whole company on building WordPress sites and plugins I’d like to say that abstracting away WordPress is why I love this plugin. Now none of my devs need to know anything about WordPress! It’s way easier to hire frontend engineers that don’t know WordPress than the other way around.

Also, I personally think WordPress’s days are numbered as a serious CMS. The future is clearly headless CMS’s, and the WP core team is going in the other direction with Gutenberg. As soon as someone makes a great open source CMS that runs on Node (basically Prismic but open source) it’s over for WordPress in my mind. I realize this is a hot take and you’re not going to agree, but this is why I like the idea of moving away from WordPress conventions as much as possible.

[hybridwebdev]

As someone that has built a whole company on building WordPress sites and plugins I’d like to say that abstracting away WordPress is why I love this plugin. Now none of my devs need to know anything about WordPress! It’s way easier to hire frontend engineers that don’t know WordPress than the other way around.

Also, I personally think WordPress’s days are numbered as a serious CMS. The future is clearly headless CMS’s, and the WP core team is going in the other direction with Gutenberg. As soon as someone makes a great open source CMS that runs on Node (basically Prismic but open source) it’s over for WordPress in my mind. I realize this is a hot take and you’re not going to agree, but this is why I like the idea of moving away from WordPress conventions as much as possible.

But...this is an interface for WP....it's not like this is an implementation that can be used for magento, joomla or some other cms. This is very tightly coupled with wp. Thus why it makes no sense to discard their conventions. Also, last I checked WP powers well over 28% of the internet. That won't just magically go to 0 when some new flavor of the month cms comes along. Although I do wholeheartedly agree that gutenburg is absolute crap and a really bad thing for wp to be throwing resources at :) When your #1 downloaded plugin in your repo is a plugin that disables your core functionality, you know you're in trouble.

[kidunot89]

In trouble in what way? That 28% you mentioned aren't just blogs and don't use WordPress to handle all core functionality. If that core functionality can be perform better in plugins, why not use it? One of the many great things about WordPress is that it's designed for outsourcing functionality like that.