Query scopes essentially allows us to define reusable query statements that we can apply into any query that we need to use. So if we dive into the documentation, we'll see an example right here.

It's provided as a static property where we call the scope and provide it in a callback method that accepts the query.

We then run whatever query statements we want to have happen for this query scope inside of this callback method. And then we can make use of it using with scopes or

even apply on the model query builder itself. Furthermore, you can also pass arguments into the query scope as well.

That comes through as the second argument within the callback function that we provide into the scope function, just like so. So here they're providing in the user where they can perform some check to see

whether or not they're administrator. If they are, they kick back. Otherwise, you perform some query action. Note that you don't need to return back an instance of the query.

We're just building off of an already bound query property. So any alterations or statements that we add on to query will get automatically applied onto the query that we're building.

So a use case that we have that would be fantastic for query scopes is checking to see whether or not a movie is actually released. Because we have both a status ID and a released at.

We need to check and make sure that both of those are set for a movie to be actually released. Because the movie status could be set to released, but the released at could be still future dated.

So we wanna make sure that the released at is somewhere in the past and the movie status ID is set to released. So for that, let's go ahead and hide our browser back away.

So we wanna jump up to the movie model. And I like declaring these after all of the model properties. And we'll provide this as static.

We'll call this released equals scope. We'll import that from Adonis Lucid ORM, provide that in a callback function.

This callback function provides to us the underlying query, where we just need to now build off of this query with the statements that we

want applied whenever we call this released query scope. So for this released query scope, what we wanna do is first query.where

our status ID equals movie statuses. And let's import that from our enums dot and set it to released.

On top of that, what we also wanna do is an additional where check, where our released at is less than or equal to date time from luxen.now.

And we'll call to SQL, so that's SQL save. There we go. Give that a save and I don't like that format. Okay, well, let's break that back down so that we can read it first.

Okay, so whenever we apply our released query scope, we're gonna be adding in two where statements. Where status ID equals released, so that's our ID of five,

as we can see right here. And our released at date time is less than or equal to date time now. So right now at this point in time.

Since we have multiple where statements being applied here and we want this to be a definite and. So where status ID and released at.

What I would prefer to do to future proof this is to nest this in parentheses. So we can provide a callback function to our where, call query inside of there.

I'm gonna get rid of that end bracket and add it down to the end here. Essentially wrapping those two where statements inside of parentheses and for the underlying SQL that will be generated.

Looks like we got a red squiggly. I think that's just cuz we have query used twice now. Yeah, we'll just replace this with group. There we go. But we also have one more determination.

Do we want null valued release stats to just default to using the status ID? I think for our use case, let's go ahead and make sure that release that's not null as well.

So let's do where not null and then that just accepts in the column name. So released, yep, down here that should be released at there as well. Okay, cool.

Essentially here if we add in some comment blocks down here, what the underlying where statement here ends up looking like is, okay, so

we have select star from movies where, I'm gonna break the where down on a separate line, and our where statement here is saying where we're wrapping these

statements inside of parentheses, so we'll have our parentheses here. Status ID equals five and released at is not null and

released at is less than or equal to whatever now is. So I'll use a little bit of pseudocode right there. So essentially this is the SQL representation of what we have within

our query scope and the reason why we're wrapping these statements inside of an additional parentheses as we are right here and right here is so that we can chain

additional statements to build additional and where statements outside of the scope of our query scope here. So let's go ahead and get rid of that and see how this works in practice.

So in order for it to work, we're gonna need some released movies. We already have about, I think, ten not released movies. So let's jump back down to our fake cedar.

We don't need additional users or synapse, so I'm just gonna comment that out. And let's create maybe two movies that are released. Now, within our factory, we have these set to,

I'm not entirely sure it was not released though, writing. So what we wanna do is merge in alternative values. So we can merge together an object and

this will override anything that we have set within our factory. So we could say our status ID is set to movie statuses,

import that and set it to released. And then our released at is we can say date, time, import that from Luxem.

Scroll down a little bit here and get rid of all these pop-ups. And we'll just set it to now and then let's subtract or

looks like the method's minus and this accepts a duration like value as an object. So we could say month one to subtract one month from this date time.

Let's give that a save, that's gonna do some formatting. And let's go ahead and run this cedar to create two movies that are released. So we'll jump back into our terminal here, node, ace, db.

And we've recently run this, so I'm gonna hit up and there it is. So I'm gonna go ahead and run that, there we go. I'm gonna go ahead and hide our text editor back away and let's enter in a rebel session.

So node, ace, rebel and let's await load models. Await models.movie.query and we have two options whenever it comes to actually

applying a query scope into our query builder statement. We could do with scopes, which is a little bit more direct with what we're doing. And then this will provide us our scopes as a callback function.

So we can do scopes. and then call the function released as we have defined in the model to apply this query scope to this query builder statement.

So if we run here, we should get back, let's add Poyo to that so that we can actually read the properties. So .poyo there, there we go.

We should get back just the movies that are explicitly released, which we have two of. We see the status ID is five for both of these.

And both these titles I don't recognize going through quite yet so far. So these are two brand new movies that we haven't seen yet and both are released.

We take a look at the release that and that is a month ago. So cool, that looks all right. Everything there is working okay.

Now if we go up, the second approach that we have to apply query scopes is instead of doing with scopes, there's an alias method just called apply.

It's shorter but not as direct with what exactly we're doing. But it is documented so if somebody were to come along curious what exactly it is, they'd be able to look in the documentation and see exactly what it does.

So this does the exact same thing. It provides us an instance of our scopes where we can call any query scopes that we have to find on the model as a method inside of this callback.

So if we run this, we're going to get back the exact same thing. And this just allows us to build out additional statements as needed and

reuse this query scope over and over again in as many queries as we need. And for our particular use case of checking to see whether or not a movie is released, this will just help us keep our queries clean,

a little bit more legible in what they're doing, and make the overall queries to get to released movies much easier to work with. So we can build out additional where statements off of this as well.

So maybe where title is, let's do 16 tons. It's a little bit shorter than the other one. So 16 tons, just like so.

And we should just get back this ID 8 record right here. And we get exactly that. So you can continue building your queries however you need.

Just be cognizant where you've defined your query scope. So if we scroll back up to our movie query scope, how you've defined the statements within here.

For example, we've wrapped these within parentheses for a very specific reason so that we can do additional or statements if we needed to outside the realms of this particular scope.

So that's query scopes in a nutshell.