Using @ and - with GraphQL

Hello again! :slight_smile:

Haven’t really found anything here in the forum, and maybe I am missing some very basic point here, but …
How to use the GraphQL API for commit/object mutations, if GraphQL neither accepts the @ (for @Data object), nor the - (for a custom parameter name e.g. “44a9894f-1aa6-4471-b8a5-3d277100c8a6”)?
Haven’t found a way to escape those either.


It seems possible to create those objects with the REST API, where those special characters are not a problem or can be “packaged” somehow, but I’d prefer sticking to the GraphQL API.

How is that possible?
In the /explorer? Via JS’s fetch()?

Thanks in advance! :slight_smile:

PS: Why is it “speckleType” for the GraphQL query and its response, and “speckle_type” in the database and also required for object mutations?
Because of this, I am seeming unable to define a common TS interface for those JSON objects. :confused:


I think I solved my second topic:

It’s “speckleType” on object level (database row), and “speckle_type” inside the “data” property (database column “data”).


1 Like

Sorry, I’ve been formulating a reply for you in my head all morning.

Yes there are two separate object definitions at play with the GraphQL API.

Those you interact with for the rows of the Speckle Data and then the eventual Payload data.

At the Query and Mutation level, you’ll not be defining a detached property (using @ or any parameter GUID) in exactly that way; mostly, you’ll be defining an address and then committing a JSON payload to that or retrieving a JSON payload from it.

And then given that payload is JSON, normal rules apply, or at least you can make things easier for yourself by encapsulating in double-quotes “”

As for defining Typescript interfaces, the GraphQL query side is straightforward enough as there is a published API to work from; the payload objects, not so much.

There is a grey area where payload data properties come into play, which is in data filtering, so a data filter can be defined as using any Speckle Object data properties (or their absence). Yet, filtering isn’t being done on GraphQL API properties - like created dates etc.

Committing a mutation via GraphQL directly where the payload uses the @ name signifier won’t do very much for you; it will work fine as a property name but won’t bring detaching or chunking as the server does not perform this If you are looking to exploit detaching in objects you are creating, then a traversal and serialization routine could use that dynamic @ signifier to help (as do we). Then the serialized JSON payload and all its detached objects are added as an object in the mutation.

We have yet to publish a good guide on a TS/JS SDK (which doesn’t exist), and these posts are a helpful reminder of what we must cover.


Hey @jonathon!

Thank you so much for your time!
The entire data structure is, I guess, a crucial point for me to understand properly. And, I guess, also hard to quickly explain.
So far, I already have been looking back and forth a lot between what’s in the database and what the GraphQL API provides and what’s displayed in the frontend … for different types of objects and geometries. Which properties will always be present by definition? And which are optional and might be missing in other cases? … And also how it corresponds to the data in the original software.

Regarding my questions:

I understand the speckleType/speckle_type thing and I can differentiate now. So that’s clarified.

Also, I will have to define two separate interfaces anyways: for the object (including things like “createdAt” and “children”) and for the object’s payload (depending on the actual speckleType, I guess?). That’s also clarified for now.

Thanks! :slight_smile:

I am still struggling with my initial question, though. Sorry, I might not have understood your reply on that… I know, that by using the @ (if it would be accepted) speckle wouldn’t detach the properties/objects automatically - at least not when using the GraphQL API. That’s fine. I thought I would do that on my own … committing the detached objects by their own first and then include them as referencedObjects inside a parent object. … which will be referenced inside a new commit. →

I marked my two problems inside the screenshots.

Currently I am getting it to work by executing the mutations without the @ and with a placeholder parameter name (without -) … and then changing those things manually directly in the database… before receiving it into Revit.

So - once the data is in place - it does work! I am just not getting it there with the GraphQL API.

Not sure what you mean with “address” here. :innocent:

1 Like

I solved that topic by using variables within the requests. Those variables accept JSON.stringify()ed objects - including parameter IDs (which include "-"s) as property names/key.

… and they also would accept the “@”. But in that case I haven’t seen any sense in detaching the Data (parameter updates), so I don’t need the “@” anymore.



2 posts were merged into an existing topic: Query to find parameters

Do you have a bit of example code you could share on how you managed to do that with the GraphQL API explorer? :slight_smile:

Hey @JdB!

I vaguely remember, that it might not have worked from inside the explorer and I got the same error message regarding the naming as without variables. But it definitely works from inside JS doing the request and sending the (stringyfied) query and variables as payload (regular http request).
But I will double-check! :slight_smile:



and then