# Just enough GROQ

https://www.sanity.io/learn/course/day-one-with-sanity-studio/a-taste-of-groq.md

You can think of GROQ as "SQL for JSON," a simple but flexible way to query anything in your dataset and reshape the response.

While Sanity also has a GraphQL API, most choose to query their Sanity content using GROQ. 

While you can think of GraphQL as a replacement for RESTful APIs, GROQ is more like SQL for JSON. In other words, you can do way more with it.

GROQ is also used for configuring parts of the Studio configuration API and project-level features like Functions, and user access control. 

1. Learn more about [GROQ and GraphQL](https://www.sanity.io/learn/content-lake/what-about-graphql) in the documentation

## Vision: The GROQ playground

The Vision tool lets you run queries against your project's dataset(s) from Sanity Studio. It comes preinstalled with new studios. In the Studio's toolbar, next to Structure, select **Vision**.

![Sanity Studio Vision tool with a query](https://cdn.sanity.io/images/3do82whm/next/929fabe40151dee3f4038b19b644a9d076c638a2-2240x1480.png)

### Querying with GROQ

To start with, you can view the most common type of GROQ expression in three parts:

```groq
*[_type == "event"]{ name }
```

* `*`: Represents **all documents** in a dataset as an array
* `[_type == "event"]` represents a **filter** where you narrow down those documents
* `{ name }` represents a **projection** where you define which **attribute** in those matching documents you want the query to return

```groq
*                  // "all documents"
[_type == "event"] // "filter"
{ name }           // "projection"
```

1. See [Query Language (GROQ)](https://www.sanity.io/learn/groq) in the documentation

1. In Vision, write your first GROQ query for all documents:

```groq
*
```

The `*` indicates you want to return every document in the target dataset, which will be returned in an array.

You can add a set of `[]` square brackets with a logical expression in them – called a filter – to return only a subset of the documents within it.

1. Filter the array to just our "event" documents:

```groq
*[_type == "event"]
```

You can stack filters for even more granular results and, to a small extent, faster responses. 

Perhaps you only want to return event documents that are marked as in-person. Yes, you can filter on _any_ key and value that your documents might have.

1. Write a query just for in-person events

```groq
*[
  _type == "event"
  && eventType == "in-person"
]
```

You could use the `now()` function here to only return upcoming in-person events

1. Write a query just for upcoming in-person events

```groq
*[
  _type == "event"
  && eventType == "in-person"
  && date > now()
]
```

1. See the documentation about [GROQ Functions Reference](https://www.sanity.io/learn/specifications/groq-functions)

Currently, every field in every returned document is being returned. This is more data than we need! Over-fetching can lead to slower queries and makes it less clear to others which attributes your application depends on.

Add a **projection** `{}` after the array filter so that for every item in the array, only certain **attributes** are returned.

1. Add a projection to return only the event name and the artist name

```groq
*[
  _type == "event"
  && eventType == "in-person"
  && date > now()
]{
  name,
  headline->{
    name
  }, 
  "isUpcoming": true
}
```

In this projection, you are doing the following:

* Returning the event's `name` as-is 
* Using the `->` to join the referenced artist document for `headline` and return just the `name` of that artist (try removing the arrow and the projection after to see the difference in the returned data)
* Defining some arbitrary data for `isUpcoming` (which is implied by the filter), demonstrating the flexibility of GROQ by creating and returning new content in the context of a query.

This is just the beginning, but it's enough for us to query Sanity content and render it in an application.

1. See [Query Cheat Sheet - GROQ](https://www.sanity.io/learn/content-lake/query-cheat-sheet) for more GROQ examples

## Next steps

You now know enough GROQ to get work done, but you could go much deeper. You might like to jump out of this course for now and complete [Between GROQ and a hard place](https://www.sanity.io/learn/course/between-groq-and-a-hard-place). 

1. Take the [Between GROQ and a hard place](https://www.sanity.io/learn/course/between-groq-and-a-hard-place) course

Otherwise if you're still racing to the finish, let's keep going onto the next lesson.