Syntax for "query" argument in GraphQL (Storefront API)

[Pedro_Netto]

Hello guys, I'm wondering what's the syntax we should use for the "query" argument many of the Objects offer. The documentarion say "String" and passing for example "Accessories" to find Products in the "Accessories" collection works. But it feels a little loose. Is there a way to make it more explicit that I'm only searching for collections called "Accessories"?

This was just an example, any information on the topic will contribute a lot! Thanks!

[Mark46]

I'm looking for the same information myself.  

You can do exact matching - e.g.

query:"title='My Title'"

I've not figured out how to do partial matches, so for me it is less useful than not providing the field but it might be what you are after.

[Pedro_Netto]

Thanks for replying! That's a confusing feature because it only seems to work in some cases. For example, if I do:

products(first: 10, query: "title='Verma'")

It works, but if I do:

products(first: 10, query: "product_type='Men'")

It does not work even though the documentation says "product_type" is supported as a filter in the query argument.

Do you see anything I might be doing wrong here?

Cheers!

[Mark_Johnson2]

I've not managed to get any of the other filters working either..  

It would be really helpful for some at Shopify to help explain how to use it. 

[Pedro_Netto]

Just got a reply from a staff at Shopify and from his response and my tests I understood that you can do things like:

products(first:10, query:"product_type:'Men'")

or

products(first:10, query:"product_type:'Men' title:'My product'")

There has to be no space between the colon and the value queried, and there is no comma between parameters. Also, it's case insensitive. 

[eugeneoei]

Hi everyone,

I know this thread is pretty long ago. but i was hoping someone could point me in the right direction.

Suppos i have two product types "Shirt" and "Baby Shirt". How do i do an exact search query for products based on its product type?

Doing the following query returns both "Shirt" and "Baby Shirt" products but i would only like to query for products that are "Shirt".

{
  products (
    first: 250,
    query: "product_type:shirt tag:Display"
  ) {
    edges {
      cursor
      node {
        title
      }
    }
    pageInfo {
      hasNextPage
    }
  }
}

According to shopify's Phrase Query  documentation, i added double quotes like so:

{
  products (
    first: 250,
    query: "product_type:\"shirt\" tag:Display"
  ) {
    edges {
      cursor
      node {
        title
      }
    }
    pageInfo {
      hasNextPage
    }
  }
}

but still i get products that are "Shirt" and "Baby Shirt". 

How can i query for products based on a specific type with exact search value?

Thanks in advance! 

[Mark46]

Great!  That helps.    Was there any info on how to do partial matches?

[vampiree007]

{

  products(first: 10, query: "title:*sleeve*") {

    edges {

      node {

        id

        title

      }

    }

  }

}

[Pedro_Netto]

Unfortunately our guy didn't say much cause he himself didn't have a lot of experience with this API. I'm hoping we'll see more developments on it soon as it's a killer feature on Shopify's tool belt 🙂

[Vipul_Kumar]

Hi,

I need to filter product list but getting this error after passing parameter in product

 products(first:10, query:"product_type:'Men' title:'My product'")

Error Message

 "message": "Field 'products' doesn't accept argument 'query'"

Please suggest

[Johan_Land]

So, this is a bit of a mess. And believe it or not, this thread is currently the best documentation on how to use the query field.

@Shopify, please help us out here as we're currently doing guesswork.

Here's what I know so far:

While you can see what query fields are claimed to be supported here (https://help.shopify.com/en/api/graphql-admin-api/reference/queryroot) it is actually not accurate. Only some of those fields are in practice supported. But, some actually do work.

I'm currently working on orders() and for this it seems that the status of the working/non-working query fields are:

- email: not working

- status: not working?

- fulfillment_status: IS WORKING

- customer_id: IS WORKING

When running queries, the correct format is this:

orders(first:3, query:"customer_id:871660388411")

The incorrect format is this (incorrectly claimed to be correct in a previous post):

orders(first:3, query:"customer_id=871660388411")

(e.g. do not use '=' but instead ':'

It seems that the query field is insensitive to extra quotations for at least numbers. The following does work:

orders(first:3, query:"customer_id:'871660388411'")

It is also insensitive to left out quotations for strings.

I hope this helps someone out there trying to get this working despite of Shopify's complete lack of documentation and support for the community.

[Zolbayar]

---

@Johan_Land wrote:

So, this is a bit of a mess. And believe it or not, this thread is currently the best documentation on how to use the query field.

@Shopify, please help us out here as we're currently doing guesswork.

Here's what I know so far:

While you can see what query fields are claimed to be supported here (https://help.shopify.com/en/api/graphql-admin-api/reference/queryroot) it is actually not accurate. Only some of those fields are in practice supported. But, some actually do work.

I'm currently working on orders() and for this it seems that the status of the working/non-working query fields are:

- email: not working

- status: not working?

- fulfillment_status: IS WORKING

- customer_id: IS WORKING

When running queries, the correct format is this:

orders(first:3, query:"customer_id:871660388411")

The incorrect format is this (incorrectly claimed to be correct in a previous post):

orders(first:3, query:"customer_id=871660388411")

(e.g. do not use '=' but instead ':'

It seems that the query field is insensitive to extra quotations for at least numbers. The following does work:

orders(first:3, query:"customer_id:'871660388411'")

It is also insensitive to left out quotations for strings.

I hope this helps someone out there trying to get this working despite of Shopify's complete lack of documentation and support for the community.

---

Indeed, it's still the best documentation on how to use the query field/

[Virtooal]

Hi 

I am new to graphql.
I have some test products in my dev store with titles like t2018, t2019, t2020
I tried this:

{
	products(first:3, query:"title:*1*") {
		edges {
			node {
				 id
				title
				 handle
			}
		 }
	}
 }

but with no success. I always get back an empty edges array

I have tried these so far (also with the handle field):

query:"title:*1*"
query:"title:'*1*'"
query:"title:1"
query:"title:'1'"
query:"title:*9"
query:"title:'*9'"

does this mean we can not search products by numbers in the title?

[Ryan]

Have you seen this doc: https://help.shopify.com/en/api/getting-started/search-syntax

[Modules4U1]

@Ryan the text field search syntax has absolutely nothing to do with the GraphQL API and its features or better the lack thereof.

This whole API would make a lot more sense to me if you could do simple QBE like:

query {
customer (id:"gid://shopify/Customer/123")
{
   metafields {
        edges {
          node {
            id
            key: "my_metafield"
          }
        }
      }
    }   
}

[PhobosTech]

I'd like to thank everybody who contributed here. You have no idea how immensely you've helped me.

I don't understand why the Shopify documentation is so insanely horrific.

I volunteer to re-build the entire documentation. Seriously.

There are a number of shining examples across the web. Both ruby-lang.org and rubyonrails.org (oh man, especially RoR's documentation) are the epitome of brilliantly designed documentations, guides, and tutorials.

Compared to Shopify's docs, both Python and PHP have god-level documentation.

I find myself saying this often enough, so I'll repeat it here because it's true: It took me 3 full months of reading and re-reading shopify's documentation, taking the nearly worthless "fun courses" in the ever-so misleadingly named "Partner's Academy", and pouring through the blogs and forums to become moderately efficient. I can guarantee you that I could re-write the documentation in a manner that would get 90% of new Shopify developers up to my current skill level in less than 3 weeks. Most, in under a week - zero exaggeration. *THAT* is how confusing and poorly organized the docs are.

First time through I was like, "Wait - they have what? 1, 2, 3 ... 57 different API's? How - what? Does that even make sense?"
Come to finally realize everything's an API here. So when you have the Discounts API, Customer API, and the Storefront API and the REST API. API's within API's, surrounding the API's and within the APIs. APIs to connect APIs that aren't even APIs. Like seriously. How insanely confusing can you make things?

So yes - totally - I suffered unnecessarily for months; I will totally rewrite these docs. Obviously not for free; but I'll make em' shine. Shopify's documentation will be legendary. People will want to learn Shopify development just so they can read the legendary docs.

Anyway - nuffsed. Thank you everybody for everything you've laid out here. Bookmarked.

[danielmorrison]

I'm noticing some inconsistencies in querying products (api versoins: 2019-04 through 2010-10)

I have a product with

title: Thing
sku: abc-123

Searching with a prefix query acts different depending on field:

query: "title:Thi*" returns the product
query: "title:Thi" no results
query: "sku:abc*" no results
query: "sku:abc" returns the product
query: "abc" returns the product
query: "abc*" returns the product

[nathanp]

Yes, most consistent across the GraphQL implementation is inconsistency. Maybe the lack of documentation is to hide this problem.

The Search Syntax link that keeps getting dropped into GraphQL query posts is not helpful. The examples in it don't work on GraphQL because many of the fields don't support query. For example, query:"name:Bob", in the search docs won't work because Shopify's GraphQL implementation does not allow for querying of the name, but it does support querying the email address....  what??

This in addition to the GraphQL interface returning 'firstName' but the search doc examples refer to 'first_name'... So even it was queryable, which would it be???

Now that Shopify has adopted versioned API's, as their GraphQL implementation so inconsistent and poorly documented, they should be tagging it as BETA until it's ready for rage-free adoption by partners/customers. Its simply not fully baked...

[Nidhi_Savaliya]

Hello, For the date field what is syntax for search query

I tried syntax but not get answer proper

{
  products(first: 250, query: "created_at:2021-5-15T10:10:10Z") {
    edges {
      node {
        id
        title
      }
    }
  }
}


{
  products(first: 250, query: "created_at:>2021-5-15T10:10:10Z created_at:<2020-05-21T12:12:12Z") {
    edges {
      node {
        id
        title
      }
    }
  }
}

[chase-mo]

yes, surprise surprise -- shopify, under the hood, is revealed to be an abomination.

i encountered the same issue and this thread while building my typescript library shopify-shepherd, which is a replacement for the official shopify-buy sdk -- here's what i've discovered for our shared quest of searching products:

the "products" query FAILS:

{
  products(first: 10, query: "(tag:appetizer) AND (tag:indian)") {
    edges {
      node {
        id
        title
      }
    }
  }
}

but this "search" query WORKS:

{
  search(first: 10, query: "(tag:appetizer) AND (tag:indian)") {
    edges {
      node {
        ... on Product {
          id
          title
        }
      }
    }
  }
}

• this search syntax document may be useful
• in this thread i hear talk about needing a "Search & Discovery" app, but after installing it, it doesn't look useful for our case, it's something to do with customizing themes or whatever

[chase-mo]

i do however, regret to report, that as far as i can tell: it is impossible to run a product query within a specific collection (let alone within a set of collections).

• rather than relying on docs, i had a much better time finding ground-truth by directly experimenting on the GraphiQL app. install the app in your shopify admin and use it, if you're trying to figure out the storefront graphql api. it's more complete than the docs.

anyways, as things stand, it looks like we're very limited in our ability to provide a search experience for users.

from what i can gather, using the storefront graphql api, here are the different viable approaches i can muster, to implement search in a custom storefront for my library:

• fetch everything up-front: (in pages of 250 products at a time)
  • this is viable if your store has less than, maybe, a thousand products -- beyond that, and the download time and size becomes worrisome
  • once everything is downloaded clientside, we can manage the search and filtering entirely ourselves. that can be a good user experience.
  • it's an abomination that shopify might drive us to this, after all, it defeats the entire purpose of pagination (which i have already implemented dutifully)
• duct-tape together the working scraps of shopify's search api:
  • well, there's no way to run a search/query inside a collection. at all.
  • we can give the users a search bar, and checkboxes for tags -- and they can use that to search/filter through *all* products.
  • then we can give users the ability to browse collections.
  • the key is that users cannot browse collections AND run searches -- the interface has to put them in either "browse collections mode", OR "search mode" -- each mode must be mutually exclusive -- we can run pagination within each of those modes

for my use-case, building the shopify-shepherd typescript library along with the store ui project sheep-cart, i'll prefer the paginated duct-tape method, as it's more robust for bigger stores -- but hopefully i'll have time to implement both modes..

[chase-mo]

oh dear.

for reasons that are entirely beyond me, for some reason my `products(query)` is now working in my graphiql explorer.

the exact same query that before, was not working -- is now working.

i don't know if the API is being sporadic, or if something's wrong with graphiql explorer, or what, but i don't like it.

i'm now finding that `totalInventory` and `quantityAvailable` is bugged out and throws unsolvable permissions errors from deprecated scopes that no longer exist -- there's not even any way to count the number of variants a product has (so i can't determine whether to show my variants ui, except to string match against "Default Value")....

good lord, this graphql api is an absolute nightmare dumpsterfire!

[chase-mo]

i just discovered that "collection_id" is a valid product query filter param. this saved my bacon.

it's supposed to be documented here, but it's not.

i literally found this by randomly guessing, and i'm not joking.

{
  products(
    first: 10
    query: "(tag:appetizer) AND (collection_id:'gid://shopify/Collection/424441479')"
  ) {
    edges {
      node {
        id
        title
      }
    }
  }
}

 this kafkaesque nightmare has me in a fugue-state.

[chase-mo]

i'm sorry everybody.

today i've been trying to implement this "collection_id", and it's not working at all.

it turns out, half of everything i've said in this thread is WRONG and only adds confusing noise. i think of myself as a good developer, but somehow, half of what i thought was working, was some kind of mirage.

somehow, lost in the hall of mirrors that is the shopify api, i fall into a cycle of false pretenses and self-delusion -- i can't tell up from down anymore.

i think i'll have to just shut up until my unofficial sdk, shopify-shepherd, is done.

i suppose going to proceed by fully separating collection-browsing from search-and-tag-filtering.

[Mattgh9152]

I can't believe that you can't search within a specific collection, it feels like this should very much be core functionality.