Improving Sanity docs for returning categories associated with a post
10 replies
Last updated: Apr 3, 2022
D
Hey folks, if I have a suggestion for improving the Sanity docs, where would be the most helpful place to make that request? Some details in🧵
Apr 2, 2022, 5:03 PM
D
I'm currently building a Sanity blog with Remix, and initially got a little stumped by how to correctly return the categories associated with a post. I first tried to do so with
I eventually realized that if I wanted to expand an array of references, I needed to use this syntax:
This is
very clearly explained in this Next.js-specific tutorial , but (unless I'm missing it) it doesn't seem to be mentioned in How Queries Work or in the Query Cheat Sheet .
Anyway,
long story short: would it be possible to include an example of this in the Joins section of the cheat sheet ? (And does Sanity already have a method of allowing folks to propose specific improvements to the docs?)
categories->which isn't correct, and would only be correct if categories contained one single reference.
I eventually realized that if I wanted to expand an array of references, I needed to use this syntax:
categories[]->
This is
very clearly explained in this Next.js-specific tutorial , but (unless I'm missing it) it doesn't seem to be mentioned in How Queries Work or in the Query Cheat Sheet .
Anyway,
long story short: would it be possible to include an example of this in the Joins section of the cheat sheet ? (And does Sanity already have a method of allowing folks to propose specific improvements to the docs?)
Apr 2, 2022, 5:13 PM
V
user A
Are there are any special cases with the naming formats? I ask because I am pretty sure I've written "category" as a type before and then "categories", without projection, works; it's not a simple concatenation to pluralize it, so are there some words it just knows?Apr 2, 2022, 9:57 PM
When it comes to arrays, objects, and references, there aren’t any words that afford any special meaning. Giving an array a type of
categoryor a document a type of
postswon’t matter to GROQ. It’s a matter of semantics and producing a content model that’s as understandable and quickly readable as possible.
Apr 2, 2022, 10:14 PM
Also, if you name something
categoryin your schema, the word
categoriesis no more related than any other word.
Apr 2, 2022, 10:16 PM
V
If that's the case, then why would categories[]-> work if that's not the type's name? In the bit you linked to it says "The naming convention of your schema doesn't matter to GROQ (as long as you get the name right)"
To be more specific with my line of questioning, what's the arbiter for rightness, to detect that we mean one field over another, enough for it to identify it as the one to expand? That
almost all of the letters are the same and none of the other fields look like it? Or does it look, when you ask for an array, to see which ones even exist and then go in order?
If we cut out the middle bit, "The naming convention...doesn't matter as long as you get the name right" almost sounds contrary to itself, unless (and this was my assumption) convention means "the format applied to it to differentiate it as the array version."
More of an open theory question, there are other more urgent things out there, just interested in the logic that gets applied internally.
To be more specific with my line of questioning, what's the arbiter for rightness, to detect that we mean one field over another, enough for it to identify it as the one to expand? That
almost all of the letters are the same and none of the other fields look like it? Or does it look, when you ask for an array, to see which ones even exist and then go in order?
If we cut out the middle bit, "The naming convention...doesn't matter as long as you get the name right" almost sounds contrary to itself, unless (and this was my assumption) convention means "the format applied to it to differentiate it as the array version."
More of an open theory question, there are other more urgent things out there, just interested in the logic that gets applied internally.
Apr 3, 2022, 4:08 AM
D
For me personally, it works because in my
So I can then write
If I hadn't already defined a document type for category in
post.jsschema
categoriesis defined as an array that contains
categoryreferences:
{
name: 'categories',
title: 'Categories',
type: 'array',
of: [{type: 'reference', to: {type: 'category'}}],
},categories[]->and GROK knows to try to expand each reference using the data associated with my
categorydocument type.
If I hadn't already defined a document type for category in
category.js, however, this wouldn't work. (Or in other words, there is no special inference. Categories here is an array of references that refer back to the
categorydocument type)
Apr 3, 2022, 11:21 AM
D
Thanks for updating the docs so quickly
The details you added are super helpful, especially the Gotcha note.
user A
! And for sharing how I can easily suggest new changes using the website 🙏The details you added are super helpful, especially the Gotcha note.
Apr 3, 2022, 11:31 AM
Hi Vincent. I appreciate your thoughtful insight, as I may have been ambiguous or misleading in those docs.
why would categories[]-> work if that’s not the type’s name?On the contrary, it will only work if it matches exactly. When I talk about naming conventions not mattering to GROQ, I only mean that GROQ doesn’t care if your use of language is singular or plural. This is pretty common across most languages, I expect, but for contrast take a look at gen1 of our GraphQL API : Given a type of
post, it would get pluralized to
allPostswhen asking for all of them. This is not the case in GROQ, so
categorywill never be related to
categories(or the butchered plural,
categorys). When you ask for 2+ documents of the type
category, the type remains as you named it in the schema.
To be more specific with my line of questioning, what’s the arbiter for rightness, to detect that we mean one field over another, enough for it to identify it as the one to expand? That almost all of the letters are the same and none of the other fields look like it? Or does it look, when you ask for an array, to see which ones even exist and then go in order?Hopefully this makes more sense given the above, but do let me know if not.
If we cut out the middle bit, “The naming convention...doesn’t matter as long as you get the name right” almost sounds contrary to itself, unless (and this was my assumption) convention means “the format applied to it to differentiate it as the array version.”I’ll think on this and revise it to try and better reflect what I’m trying to say.
Apr 3, 2022, 7:00 PM
I’m glad that helped and that you’re up and running, Dakota. I’m not sure if your first reply (“For me personally…“) was to Vincent or to me, but you’ve touched on that fact that there are some cases where you’ll do
categories[]->and other cases where you’ll do
categories[].category->. If
categoriesis an array of objects that contain references, you’ll need the latter. A perfect example is images, which contain plenty of data but also a reference to asset. (Well, not a perfect example, as
imagewill be an object, not an array.)
Apr 3, 2022, 7:03 PM
V
user A
Thanks for taking the time to clarify; it must be my mistake, as I could have sworn both my experience and doc examples used the "ies" for category things.This isn't your official documentation, but it's the kind of thing I feel like I see a lot so I must be conflating things:
https://www.sanity.io/schemas/groq-query-to-find-all-the-different-categeries-of-products-74fa4689 It's kind of sneaky on the part of my brain because a snippet of a query doesn't let you know about the schemas that underlie it; additionally it could be demonstrating things that are merely representational.
Ultimately the most important answer with respect to my understanding of the query engine is there, that while there may be reserved words, invented/custom type names never get transformed. You all are truly generous with your time and thoroughness!
Apr 3, 2022, 11:33 PM
Sanity– build remarkable experiences at scale
Sanity is a modern headless CMS that treats content as data to power your digital business. Free to get started, and pay-as-you-go on all plans.