Local graphiql doesn't tell me when metafield filtering is disabled

GraphQL Admin API Troubleshooting
1

Just spent half an hour trying to find out why my filters aren’t working. When I add an invalid syntax I get an error, but when filtering on a metafield isn’t explicitly enabled (Use metafield capabilities), it won’t tell me and I just have to guess why it’s not working.

In my case I’m searching for something like query: "metafields.namespace.name:\"test\""

  • This does not give me an error when it doesn’t exist
  • This does not give me an error when filtering is disabled

When I do query: "metafields.namespace.name.value:\"test\""

I get:

    "search": [
      {
        "path": [
          "orders"
        ],
        "query": "metafields.namespace.name.value:\"test\"",
        "parsed": {
          "field": "metafields.namespace.name.value",
          "match_phrase": "test"
        },
        "warnings": [
          {
            "field": "metafields.namespace.name.value",
            "message": "Invalid search field for this query.",
            "code": "invalid_field"
          }
        ]
      }
    ]

It would be really nice if I would actually get errors back when things are invalid, so I no longer have to guess wtf is going on.

2

Hey @Lynn-srs! You’re right that this is a rough edge. I tested it and can reproduce the difference you described.

The current behavior is that metafields.{namespace}.{key}:... is treated as valid Admin API search syntax, so it only gets an invalid_field warning when the field shape itself is invalid, like metafields.namespace.name.value.

If the definition is missing, or the definition exists but adminFilterable is disabled, the documented behavior is that the query returns unfiltered results rather than a warning.

You can check the definition before relying on the filter with:

query CheckMetafieldFilterability {
  metafieldDefinitions(
    first: 1
    ownerType: ORDER
    query: "namespace:custom key:your_key"
  ) {
    nodes {
      namespace
      key
      capabilities {
        adminFilterable {
          eligible
          enabled
          status
        }
      }
    }
  }
}

For the filter to work, you want enabled to be true and status to be FILTERABLE. I agree GraphiQL/API warnings could be clearer here, so I’ve captured that feedback internally. Thanks for raising this!

3

I ended up solving it by syncing our desired metafield definitions to whatever the app has, and indeed fixed it by setting that value.

Thanks for forwarding it. Having a warning would already be nice, but having an error would be perfect. Last thing I want is someone disabling the filter and it returning results I did not expect.