Vertex variable vs vertex id, vs internal id vs Graph Studio

Quick clarification around Vertex variable / PrimaryId and vertex ID. Some confusion here.
When a query has as parameter (Vertex<Country> z) what is it exactly expecting ? Is it the primary ID of the vertex ? Because, when using studio that is what is happening.

At the same time we have situation all over the documentation where the parameter of the query is (STRING uid) and then in the function we find things like z = to_vertex (uid, vtype);.

I am not sure to understand very well the difference is. What is the difference between z and **uid **as parameters ? what value should be passed for each ?
Is there an implicit conversion done by Graphstudio from a string to a vertex ID ?

Overall when reading the documentation it feels like there seems to be a difference between a vertex variable and its primary Id and its internal id.

One of the component of TG is called ID Service(GSE). GSE manages a bidirectional external ID to internal ID mapping.

Here, you string id uid is the external ID, and the parameter z under VERTEX type is in the internal ID format.

Internal ID is a integer that can be used to find a vertex’s location in the graph storage. When you call the query, you would pass a string value to parameter z. This way, TG will translate the input string value for z to an internal id format before running the query. However when you call to_vertex, it does the translation inside the query.

Hope this answers your question.

@xinyu so you are saying that the translation is not happening from within GraphStudio, but that that it is a mechanism of GSQL directlty.

So whenever i have a query or a sub-query that expect a vertex in a parameter as in
(Vertex<Country> z) i can pass a string instead (primary_id), and the interpreter of tiger graph will figure out what i am passing and do the translation if necessary ?

I guess what is confusing here, is the typing system. My type says, vertex, but then i am passing a string and it works.

Cause if i have sub-query in my outer query, i will usually pass vertex variable of the require typed of vertex which you says is actually internal id. GraphStudio will check that i am passing the required type.

PS: I watch your webinar GSQL part 4 best practice and understand the service translation. It is just that from a language perspective, the typing system confuses.

E.g. If i have a sub-query call in my outer query for a sub-query that expect a vertex, can i pass a string ?


I have just tested.

With Studio i created a query

CREATE QUERY subquery(Vertex e) FOR GRAPH PPI {
/* Write query logic here */
PRINT “subquery works!”;

Published it.

Then from another query,

I try to make the call:


I know it is not a proper primary id for any vertex, but it is just to test and understand.

Studio complained and said it is the wrong type.

So clearly, that does not work with a sub-query call.

So how come if i go to Explore Graph in GraphStudio, and type, execute installed query, Studio suggest me to provide a vertex type and and a vertexid for that query? Which when i type is just a string after all.


Note that i also try to declare a vertex in the outer query and try to pass the id to the sub-query and it did not work either.

Vertex e;

subquery(; // Graph studio complain about the type. Vertex is required and i am passing a string.

however this works


So clearly there seem to be some magic going on in graph studio, which might not work is calling from a rest API. That is what i am concerned about.

I think it would benefit everyone if that could be clarified.

My conclusion is that most of the querries are written such that they are called from graph studio. But if you were calling them from rest it would not work. You would have to pass uid, and then to_vertex internally in the query.

Maybe, graph studio has has a query that call your query on demand, and in that query, it actually call to_vertex.

Otherwise i am lost.
Please help clarify.

Your observation is correct when you call it via REST API or GraphStudio. The translation happens after the parameter is passed.

When you call the query from a query, there is no transaction step by default. Then you have to pass an internal format (VERTEX type) as the input of your subquery.

To build on Xinyu’s answer…
I think you’re missing the following fact:

Your query receives a parameter Vertex<Country> z
When you run the query in Graph Studio, you don’t only pass the ID of the Country vertex.
You also pass the TYPE “Country” !
So basically, you’re passing in the pair of (Vertex ID,Vertex Type).

You can actually see it when you click the “Show query endpoint” icon image
When you click on it, you’ll see that the request parameters are going to have both “z” and “z.type

Hope it helps :slight_smile:

1 Like

@DenisK I think I got it. However your answer further stress my point.

You are saying that my query input parameter is (Vertex<Country> z)
and trough studio i am providing (Vertex ID,Vertex Type)

That is a type mismatch, which suggest that something is happening implicitly. It is that implicit aspect that i wanted to surface. I think @xinyu answer it.

1 Like